scripts.mdnreader Namespace Reference

Classes
class	MDNReader

Functions
	_get_browser_compat_data ()
	_unify_versions (version_a, version_b)
	_is_simple_support_statement (support_statement)

Variables
str	_COMPAT_KEY = '__compat'
str	_EXPERIMENTAL_KEY = 'experimental'
str	_STATUS_KEY = 'status'
str	_SUPPORT_KEY = 'support'
str	_VERSION_ADDED_KEY = 'version_added'

Function Documentation

_get_browser_compat_data()

scripts.mdnreader._get_browser_compat_data ( )

protected

Definition at line 18 of file mdnreader.py.

def _get_browser_compat_data():
    current_dir = os.path.dirname(__file__)
 
    browser_compat_folder = os.path.abspath(
        os.path.join(current_dir, '..', '..', '..', 'third_party', 'mdn',
                     'browser-compat-data', 'src'))
 
    if not os.path.exists(browser_compat_folder):
        raise RuntimeError('Browser compatibility data not found at %s' %
                           browser_compat_folder)
 
    browser_compat_data = {}
 
    INCLUDE_DIRS = [
        'api',
        'html',
        'svg',
        # TODO(srujzs): add more if needed
    ]
 
    # Transform to absolute paths
    INCLUDE_DIRS = [
        os.path.join(browser_compat_folder, dir) for dir in INCLUDE_DIRS
    ]
 
    def process_json_dict(json_dict):
        # Returns a tuple of the interface name and the metadata corresponding
        # to it.
        if 'api' in json_dict:
            # Get the interface name
            api_dict = json_dict['api']
            interface_name = next(iter(api_dict))
            return (interface_name, api_dict[interface_name])
        elif 'html' in json_dict:
            html_dict = json_dict['html']
            if 'elements' in html_dict:
                elements_dict = html_dict['elements']
                element_name = next(iter(elements_dict))
                # Convert to WebCore name
                interface = str('HTML' + element_name + 'Element')
                return (interface, elements_dict[element_name])
        elif 'svg' in json_dict:
            svg_dict = json_dict['svg']
            if 'elements' in svg_dict:
                elements_dict = svg_dict['elements']
                element_name = next(iter(elements_dict))
                # Convert to WebCore name
                interface = str('SVG' + element_name + 'Element')
                return (interface, elements_dict[element_name])
        return (None, None)
 
    # Attempts to unify two compatibility infos by taking the union of both, and
    # for conflicting information, taking the "stricter" of the two versions.
    # Updates `a` in place to represent the union of `a` and `b`.
    def _unify_compat(a, b):
 
        def _has_compat_data(metadata):
            return _COMPAT_KEY in metadata and _SUPPORT_KEY in metadata[_COMPAT_KEY]
 
        # Unifies the support statements of both metadata and updates
        # `support_a` in place. If either metadata do not contain simple support
        # statements, defaults attribute to not supported.
        def _unify_support(support_a, support_b):
            for browser in support_a.keys():
                if browser in support_b:
                    if _is_simple_support_statement(support_a[browser]) and _is_simple_support_statement(support_b[browser]):
                        support_a[browser][_VERSION_ADDED_KEY] = _unify_versions(
                            support_a[browser][_VERSION_ADDED_KEY],
                            support_b[browser][_VERSION_ADDED_KEY])
                    else:
                        # Only support simple statements for now.
                        support_a[browser] = {_VERSION_ADDED_KEY: None}
            for browser in support_b.keys():
                if not browser in support_a:
                    support_a[browser] = support_b[browser]
 
        if not _has_compat_data(b):
            return
        if not _has_compat_data(a):
            a[_COMPAT_KEY] = b[_COMPAT_KEY]
            return
 
        support_a = a[_COMPAT_KEY][_SUPPORT_KEY]
        support_b = b[_COMPAT_KEY][_SUPPORT_KEY]
 
        _unify_support(support_a, support_b)
 
    # Unifies any status info in the two metadata. Modifies `a` in place to
    # represent the union of both `a` and `b`.
    def _unify_status(a, b):
 
        def _has_status(metadata):
            return _COMPAT_KEY in metadata and _STATUS_KEY in metadata[_COMPAT_KEY]
 
        # Modifies `status_a` in place to combine "experimental" tags.
        def _unify_experimental(status_a, status_b):
            # If either of the statuses report experimental, assume attribute is
            # experimental.
            status_a[_EXPERIMENTAL_KEY] = status_a.get(
                _EXPERIMENTAL_KEY, False) or status_b.get(_EXPERIMENTAL_KEY, False)
 
        if not _has_status(b):
            return
        if not _has_status(a):
            a[_COMPAT_KEY] = b[_COMPAT_KEY]
            return
 
        status_a = a[_COMPAT_KEY][_STATUS_KEY]
        status_b = b[_COMPAT_KEY][_STATUS_KEY]
 
        _unify_experimental(status_a, status_b)
 
    # If there exists multiple definitions of the same interface metadata e.g.
    # elements, this attempts to unify the compatibilities for the interface as
    # well as for each attribute.
    def _unify_metadata(a, b):
        # Unify the compatibility statement and status of the API or element.
        _unify_compat(a, b)
        _unify_status(a, b)
        # Unify the compatibility statement and status of each attribute.
        for attr in list(a.keys()):
            if attr == _COMPAT_KEY:
                continue
            if attr in b:
                _unify_compat(a[attr], b[attr])
                _unify_status(a[attr], b[attr])
        for attr in b.keys():
            if not attr in a:
                a[attr] = b[attr]
 
    for (dir_path, dirs, files) in os.walk(browser_compat_folder):
 
        def should_process_dir(dir_path):
            if os.path.abspath(dir_path) == browser_compat_folder:
                return True
            for dir in INCLUDE_DIRS:
                if dir_path.startswith(dir):
                    return True
            return False
 
        if should_process_dir(dir_path):
            for name in files:
                file_name = os.path.join(dir_path, name)
                (interface_path, ext) = os.path.splitext(file_name)
                if ext == '.json':
                    with open(file_name) as src:
                        json_dict = json.load(src)
                        interface, metadata = process_json_dict(json_dict)
                        if not interface is None:
                            # Note: interface and member names do not
                            # necessarily have the same capitalization as
                            # WebCore, so we keep them all lowercase for easier
                            # matching later.
                            interface = interface.lower()
                            metadata = {
                                member.lower(): info
                                for member, info in metadata.items()
                            }
 
                            if interface in browser_compat_data:
                                _unify_metadata(browser_compat_data[interface],
                                                metadata)
                            else:
                                browser_compat_data[interface] = metadata
        else:
            dirs[:] = []  # Do not go underneath
 
    return browser_compat_data
 
 
# Given two version values for a given browser, chooses the more strict version.

_is_simple_support_statement()

scripts.mdnreader._is_simple_support_statement (   support_statement )

protected

Definition at line 239 of file mdnreader.py.

def _is_simple_support_statement(support_statement):
    if isinstance(support_statement, list):  # array_support_statement
        # TODO(srujzs): Parse this list to determine compatibility. Will
        # likely require parsing for 'version_removed' keys. Notes about
        # which browser version enabled this attribute for which
        # platform also complicates things. For now, we assume it's not
        # compatible.
        return False
    if len(support_statement.keys()) > 1:
        # If it's anything more complicated than 'version_added', like
        # 'notes' that specify platform versions, we assume it's not
        # compatible.
        return False
    return True
 
 

_unify_versions()

scripts.mdnreader._unify_versions (   version_a,   version_b  )

protected

Definition at line 189 of file mdnreader.py.

def _unify_versions(version_a, version_b):
    # Given two valid version strings, compares parts of the version string
    # iteratively.
    def _greater_version(version_a, version_b):
        version_a_split = list(map(int, version_a.split('.')))
        version_b_split = list(map(int, version_b.split('.')))
        for i in range(min(len(version_a_split), len(version_b_split))):
            if version_a_split[i] > version_b_split[i]:
                return version_a
            elif version_a_split[i] < version_b_split[i]:
                return version_b
        return version_a if len(version_a_split) > len(
            version_b_split) else version_b
 
    # Validate that we can handle the given version.
    def _validate_version(version):
        if not version:
            return False
        if version is True:
            return True
        if isinstance(version, str):
            pattern = re.compile('^([0-9]+\.)*[0-9]+$')
            if not pattern.match(version):
                # It's possible for version strings to look like '<35'. We don't
                # attempt to parse the conditional logic, and just default to
                # potentially incompatible.
                return None
            return version
        else:
            raise ValueError(
                'Type of version_a was not handled correctly! type(version) = '
                + str(type(version)))
 
    version_a = _validate_version(version_a)
    version_b = _validate_version(version_b)
    # If one version reports not supported, default to not supported.
    if not version_a or not version_b:
        return False
    # If one version reports always supported, the other version can only be
    # more strict.
    if version_a is True:
        return version_b
    if version_b is True:
        return version_a
 
    return _greater_version(version_a, version_b)
 
 
# At this time, we only handle simple support statements due to the complexity
# and variability around support statements with multiple elements.

Variable Documentation

_COMPAT_KEY

str scripts.mdnreader._COMPAT_KEY = '__compat'

protected

Definition at line 11 of file mdnreader.py.

_EXPERIMENTAL_KEY

str scripts.mdnreader._EXPERIMENTAL_KEY = 'experimental'

protected

Definition at line 12 of file mdnreader.py.

_STATUS_KEY

str scripts.mdnreader._STATUS_KEY = 'status'

protected

Definition at line 13 of file mdnreader.py.

_SUPPORT_KEY

str scripts.mdnreader._SUPPORT_KEY = 'support'

protected

Definition at line 14 of file mdnreader.py.

_VERSION_ADDED_KEY

str scripts.mdnreader._VERSION_ADDED_KEY = 'version_added'

protected

Definition at line 15 of file mdnreader.py.