Docserver: separate models for apps and extensions

chrome/common/extensions/docs/server2/features_utility.py

-# Copyright 2013 The Chromium Authors. All rights reserved.
-# Use of this source code is governed by a BSD-style license that can be
-# found in the LICENSE file.
-
-'''
-Utility functions for working with the Feature abstraction. Features are grouped
-into a dictionary by name. Each Feature is guaranteed to have the following two
-keys:
-  name - a string, the name of the feature
-  platform - a list containing 'apps' or 'extensions', both, or neither.
-
-A Feature may have other keys from a _features.json file as well. Features with
-a whitelist are ignored as they are only useful to specific apps or extensions.
-'''
-
-from copy import copy
-
-from branch_utility import BranchUtility
-
-
-def _GetPlatformsForExtensionTypes(extension_types):
-  platforms = []
-  if extension_types == 'all' or 'platform_app' in extension_types:
-    platforms.append('apps')
-  if extension_types == 'all' or 'extension' in extension_types:
-    platforms.append('extensions')
-  return platforms
-
-
-def Parse(features_json):
-  '''Process JSON from a _features.json file, standardizing it into a dictionary
-  of Features.
-  '''
-  features = {}
-
-  def ignore_feature(name, value):
-    '''Returns true if this feature should be ignored. Features are ignored if
-    they are only available to whitelisted apps or component extensions/apps, as
-    in these cases the APIs are not available to public developers.
-
-    Private APIs are also unavailable to public developers, but logic elsewhere
-    makes sure they are not listed. So they shouldn't be ignored via this
-    mechanism.
-    '''
-    if name.endswith('Private'):
-      return False
-    return value.get('location') == 'component' or 'whitelist' in value
-
-  for name, rawvalue in features_json.iteritems():
-    # Some feature names correspond to a list, typically because they're
-    # whitelisted in stable for certain extensions and available in dev for
-    # everybody else. Force a list down to a single feature by attempting to
-    # remove the entries that don't affect the typical usage of an API.
-    if isinstance(rawvalue, list):
-      available_values = [subvalue for subvalue in rawvalue
-                          if not ignore_feature(name, subvalue)]
-      if not available_values:
-        continue
-
-      if len(available_values) == 1:
-        value = available_values[0]
-      else:
-        # Multiple available values probably implies different feature
-        # configurations for apps vs extensions. Currently, this is 'commands'.
-        # To get the ball rolling, add a hack to combine the extension types.
-        # See http://crbug.com/316194.
-        extension_types = set()
-        for available_value in available_values:
-          extension_types.update(available_value.get('extension_types', ()))
-
-        # For the base value, select the one with the most recent availability.
-        channel_names = BranchUtility.GetAllChannelNames()
-        available_values.sort(
-            key=lambda v: channel_names.index(v.get('channel', 'stable')))
-
-        # Note: copy() is enough because only a single toplevel key is modified.
-        value = copy(available_values[0])
-        value['extension_types'] = list(extension_types)
-    else:
-      value = rawvalue
-
-    if ignore_feature(name, value):
-      continue
-
-    # Now we transform 'extension_types' into the more useful 'platforms'.
-    #
-    # But first, note that 'platforms' has a double meaning. In the docserver
-    # model (what we're in the process of generating) it means 'apps' vs
-    # 'extensions'. In the JSON features as read from Chrome it means 'win' vs
-    # 'mac'. Ignore the latter.
-    value.pop('platforms', None)
-    extension_types = value.pop('extension_types', None)
-
-    platforms = []
-    if extension_types is not None:
-      platforms = _GetPlatformsForExtensionTypes(extension_types)
-
-    features[name] = {
-      'name': name,
-      'platforms': platforms,
-    }
-    features[name].update(value)
-
-  return features
-
-
-def Filtered(features, platform):
-  '''Create a new Features dictionary from |features| that contains only items
-  relevant to |platform|. Feature values are unmodified; callers should
-  deepcopy() if they need to modify them.
-  '''
-  return dict((name, feature) for name, feature in features.iteritems()
-              if platform in feature['platforms'])
-
-
-def MergedWith(features, other):
-  '''Merge |features| with an additional dictionary to create a new features
-  dictionary. If a feature is common to both |features| and |other|, then it is
-  merged using the standard dictionary update instead of being overwritten.
-  Returns the new Features dictionary.
-  '''
-  for key, value in other.iteritems():
-    if key in features:
-      features[key].update(value)
-    else:
-      features[key] = value
-
-    # Ensure the Feature schema is enforced for all added items.
-    if not 'name' in features[key]:
-      features[key]['name'] = key
-    if not 'platforms' in features[key]:
-      features[key]['platforms'] = []
-
-  return features