Docserver: Add template support for object level availability

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

 # Copyright (c) 2012 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.
 
 from copy import copy
 import logging
 import os
 import posixpath
 
 from data_source import DataSource
@@ skipping 47 matching lines @@
   type Event.  Returns a dictionary mapping the name of a member to that
   member's definition.
   '''
   assert 'types' in events, \
       'The dictionary |events| must contain the key "types".'
   event_list = [t for t in events['types'] if t.get('name') == 'Event']
   assert len(event_list) == 1, 'Exactly one type must be called "Event".'
   return _GetByNameDict(event_list[0])
 
 
+class _APINodeCursor(object):
+  '''An abstract representation of a node in an APISchemaGraph.
+  The current position in the graph is represented by a path into the
+  underlying dictionary. So if the APISchemaGraph is:
+
+    {
+      'tabs': {
+        'types': {
+          'Tab': {
+            'properties': {
+              'url': {
+                ...
+              }
+            }
+          }
+        }
+      }
+    }
+
+  then the 'url' property would be represented by:
+
+    ['tabs', 'types', 'Tab', 'properties', 'url']
+  '''
+  def __init__(self, availability_finder, namespace_name):
+    # The cursor begins life at the root.
+    self._lookup_path = [namespace_name]
+    self._node_availabilities = availability_finder.GetAPINodeAvailability(
+        namespace_name)
+    self._namespace_name = namespace_name
+
+  def _GetParentPath(self):
+    '''Returns the path pointing to this node's parent.
+    '''
+    assert len(self._lookup_path) > 2, \
+        'Tried to look up parent for the top-level node.'
+
+    # lookup_path[-1] is the name of the current node.
+    # lookup_path[-2] is this node's category (e.g. types, events, etc.).
+    # Thus, the parent node is described by lookup_path[:-2].
+    return self._lookup_path[:-2]
+
+  def _LookupNodeAvailability(self):
+    '''Returns the ChannelInfo object for this node.
+    '''
+    return self._node_availabilities.Lookup(*self._lookup_path).annotation
+
+  def _LookupParentNodeAvailability(self):
+    '''Returns the ChannelInfo object for this node's parent.
+    '''
+    return self._node_availabilities.Lookup(*self._GetParentPath()).annotation
+
+  def _CheckNamespacePrefix(self):
+    '''API schemas may prepend the namespace name to top-level types
+    (e.g. declarativeWebRequest > types > declarativeWebRequest.IgnoreRules),
+    but just the base name (here, 'IgnoreRules') will be in the |lookup_path|.
+    Try creating an alternate |lookup_path| by adding the namespace name.
+    '''
+    # lookup_path[0] is always the API namespace, and
+    # lookup_path[1] is always the node category (e.g. types, functions, etc.).
+    # Thus, lookup_path[2] is always the top-level node name.
+    base_name = self._lookup_path[2]
+    self._lookup_path[2] = '%s.%s' % (self._namespace_name, base_name)
+    node_availability = self._LookupNodeAvailability()
+    if node_availability is not None:
+      return node_availability
+    # We want to maintain a working lookup_path, so only restore it
+    # if modifying the lookup_path did not work.
+    self._lookup_path[2] = base_name
+    return None
+
+  def _CheckEventCallback(self):
+    '''Within API schemas, an event has a list of 'properties' that the event's
+    callback expects. The callback itself is not explicitly represented in the
+    schema. However, when creating an event node in _JSCModel, a callback node
+    is generated and acts as the parent for the event's properties.
+    Modify |lookup_path| to check the original schema format.
+    '''
+    if 'events' in self._lookup_path and 'callback' in self._lookup_path:
+      self._lookup_path.remove('callback')

[ahernandez, 2014/06/27 03:00:01]

I'm not sure if this should be restored or not.

+      return self._LookupNodeAvailability()
+    return None
+
+  def GetAvailability(self):
+    '''Returns availability information for this node.
+    '''
+    if self._lookup_path[0] != self._namespace_name:
+      # |lookup_path| won't be lookup up if it doesn't start with the API name.
+      return None
+
+    for lookup in (self._LookupNodeAvailability,
+                   self._CheckEventCallback,
+                   self._CheckNamespacePrefix):
+      node_availability = lookup()
+      if node_availability is not None:
+        break
+
+    if node_availability is None:
+      logging.warning('No availability found for: %s' % ' > '.join(
+        self._lookup_path))
+      return None
+
+    # Only render this node's availability if it differs from the parent
+    # node's availability.
+    if node_availability == self._LookupParentNodeAvailability():
+      return None
+    return node_availability
+
+  def DescendTo(self, *path):
+    '''Moves down the APISchemaGraph, following |path|.
+    '''
+    self._lookup_path.extend(path)
+
+  def Ascend(self):
+    '''Moves to the parent node.
+    '''
+    self._lookup_path = self._GetParentPath()
+
+
 class _JSCModel(object):
   '''Uses a Model from the JSON Schema Compiler and generates a dict that
   a Handlebar template can use for a data source.
   '''
 
   def __init__(self,
                namespace,
-               availability,
+               availability_finder,
                json_cache,
                template_cache,
                features_bundle,
                event_byname_future):
-    self._availability = availability
+    self._availability = availability_finder.GetAPIAvailability(namespace.name)
+    self._current_node = _APINodeCursor(availability_finder, namespace.name)
     self._api_availabilities = json_cache.GetFromFile(
         posixpath.join(JSON_TEMPLATES, 'api_availabilities.json'))
     self._intro_tables = json_cache.GetFromFile(
         posixpath.join(JSON_TEMPLATES, 'intro_tables.json'))
     self._api_features = features_bundle.GetAPIFeatures()
     self._template_cache = template_cache
     self._event_byname_future = event_byname_future
     self._namespace = namespace
 
   def _GetLink(self, link):
@@ skipping 28 matching lines @@
   def _GetChannelWarning(self):
     if not self._IsExperimental():
       return {
         self._availability.channel_info.channel: True
       }
     return None
 
   def _IsExperimental(self):
     return self._namespace.name.startswith('experimental')
 
-  def _GenerateTypes(self, types):
-    return [self._GenerateType(t) for t in types]
+  def _GenerateTypes(self, types, no_gen=False):
+    return [self._GenerateType(t, no_gen=no_gen) for t in types]
 
-  def _GenerateType(self, type_):
+  def _GenerateType(self, type_, no_gen=False):
+    '''If |no_gen| is True, don't generate availability info.
+    '''
+    self._current_node.DescendTo('types', type_.simple_name)
     type_dict = {
       'name': type_.simple_name,
       'description': type_.description,
       'properties': self._GenerateProperties(type_.properties),
       'functions': self._GenerateFunctions(type_.functions),
       'events': self._GenerateEvents(type_.events),
-      'id': _CreateId(type_, 'type')
+      'id': _CreateId(type_, 'type'),
+      'availability': None if no_gen else self._GetAvailabilityTemplate()
     }
+    self._current_node.Ascend()

[ahernandez, 2014/06/27 03:00:01]

I'm not sure if the whole purpose of the APINodeCursor Ascend and DescendTo
methods are obvious, so I'll explain the idea I have in mind here. Each time a
Generate?() method is called, the function will call current_node.DescendTo() to
get availability data for that node if necessary. Once the function is done with
that node, it calls current_node.Ascend() to return back to where it was at
previously. By doing this, I think it is possible to eliminate having to pass
around some sort of lookup_path object everywhere.

     self._RenderTypeInformation(type_, type_dict)
     return type_dict
 
   def _GenerateFunctions(self, functions):
     return [self._GenerateFunction(f) for f in functions.values()]
 
   def _GenerateFunction(self, function):
     function_dict = {
       'name': function.simple_name,
       'description': function.description,
       'callback': self._GenerateCallback(function.callback),
       'parameters': [],
       'returns': None,
       'id': _CreateId(function, 'method')
     }
     self._AddCommonProperties(function_dict, function)
     if function.returns:
-      function_dict['returns'] = self._GenerateType(function.returns)
+      function_dict['returns'] = self._GenerateType(function.returns,
+                                                    no_gen=True)

[ahernandez, 2014/06/27 03:00:01]

I think I now understand what the deal with the blank paths is. Namespace
objects contain a lot of values that don't need availability information
generated, such as where I left this comment. By passing in a blank path, the
check we discussed earlier prevented availability data from being generated.
However, that was clearly confusing, so I added this no_gen keyword arg that
just indicates whether or not availability data should be generated.

     for param in function.params:
       function_dict['parameters'].append(self._GenerateProperty(param))
     if function.callback is not None:
       # Show the callback as an extra parameter.
       function_dict['parameters'].append(
           self._GenerateCallbackProperty(function.callback))
     if len(function_dict['parameters']) > 0:
       function_dict['parameters'][-1]['last'] = True
     return function_dict
 
@@ skipping 90 matching lines @@
       'returns': None,
       'id': _CreateId(property_, 'property')
     }
     self._AddCommonProperties(property_dict, property_)
 
     if type_.property_type == model.PropertyType.FUNCTION:
       function = type_.function
       for param in function.params:
         property_dict['parameters'].append(self._GenerateProperty(param))
       if function.returns:
-        property_dict['returns'] = self._GenerateType(function.returns)
+        property_dict['returns'] = self._GenerateType(function.returns,
+                                                      no_gen=True)
 
     value = property_.value
     if value is not None:
       if isinstance(value, int):
         property_dict['value'] = _FormatValue(value)
       else:
         property_dict['value'] = value
     else:
       self._RenderTypeInformation(type_, property_dict)
 
     return property_dict
 
   def _GenerateCallbackProperty(self, callback):
     property_dict = {
       'name': callback.simple_name,
       'description': callback.description,
       'optional': callback.optional,
       'is_callback': True,
       'id': _CreateId(callback, 'property'),
       'simple_type': 'function',
     }
     if (callback.parent is not None and
         not isinstance(callback.parent, model.Namespace)):
       property_dict['parentName'] = callback.parent.simple_name
     return property_dict
 
   def _RenderTypeInformation(self, type_, dst_dict):
     dst_dict['is_object'] = type_.property_type == model.PropertyType.OBJECT
     if type_.property_type == model.PropertyType.CHOICES:
-      dst_dict['choices'] = self._GenerateTypes(type_.choices)
+      dst_dict['choices'] = self._GenerateTypes(type_.choices, no_gen=True)
       # We keep track of which == last for knowing when to add "or" between
       # choices in templates.
       if len(dst_dict['choices']) > 0:
         dst_dict['choices'][-1]['last'] = True
     elif type_.property_type == model.PropertyType.REF:
       dst_dict['link'] = self._GetLink(type_.ref_type)
     elif type_.property_type == model.PropertyType.ARRAY:
-      dst_dict['array'] = self._GenerateType(type_.item_type)
+      dst_dict['array'] = self._GenerateType(type_.item_type, no_gen=True)
     elif type_.property_type == model.PropertyType.ENUM:
       dst_dict['enum_values'] = [
           {'name': value.name, 'description': value.description}
           for value in type_.enum_values]
       if len(dst_dict['enum_values']) > 0:
         dst_dict['enum_values'][-1]['last'] = True
     elif type_.instance_of is not None:
       dst_dict['simple_type'] = type_.instance_of
     else:
       dst_dict['simple_type'] = type_.property_type.name
@@ skipping 11 matching lines @@
     # if they share the same 'title' attribute.
     row_titles = [row['title'] for row in intro_rows]
     for misc_row in self._GetMiscIntroRows():
       if misc_row['title'] in row_titles:
         intro_rows[row_titles.index(misc_row['title'])] = misc_row
       else:
         intro_rows.append(misc_row)
 
     return intro_rows
 
+  def _GetAvailabilityTemplate(self, status=None, version=None, scheduled=None):
+    '''Returns an object that the templates use to display availability
+    information.
+    '''
+    if status is None:
+      availability_info = self._current_node.GetAvailability()
+      if availability_info is None:
+        return None
+      status = availability_info.channel
+      version = availability_info.version
+    return {
+        'partial': self._template_cache.GetFromFile(
+          '%sintro_tables/%s_message.html' % (PRIVATE_TEMPLATES, status)).Get(),
+        'version': version,
+        'scheduled': scheduled
+    }
+
   def _GetIntroDescriptionRow(self):
     ''' Generates the 'Description' row data for an API intro table.
     '''
     return {
       'title': 'Description',
       'content': [
         { 'text': self._namespace.description }
       ]
     }
 
   def _GetIntroAvailabilityRow(self):
     ''' Generates the 'Availability' row data for an API intro table.
     '''
     if self._IsExperimental():
       status = 'experimental'
       version = None
       scheduled = None
     else:
       status = self._availability.channel_info.channel
       version = self._availability.channel_info.version
       scheduled = self._availability.scheduled
     return {
       'title': 'Availability',
-      'content': [{
-        'partial': self._template_cache.GetFromFile(
-          posixpath.join(PRIVATE_TEMPLATES,
-                         'intro_tables',
-                         '%s_message.html' % status)).Get(),
-        'version': version,
-        'scheduled': scheduled
-      }]
+      'content': [
+        self._GetAvailabilityTemplate(status=status,
+                                      version=version,
+                                      scheduled=scheduled)
+      ]
     }
 
   def _GetIntroDependencyRows(self):
     # Devtools aren't in _api_features. If we're dealing with devtools, bail.
     if 'devtools' in self._namespace.name:
       return []
 
     api_feature = self._api_features.Get().get(self._namespace.name)
     if not api_feature:
       logging.error('"%s" not found in _api_features.json' %
@@ skipping 119 matching lines @@
   def _GetSchemaModel(self, platform, api_name):
     object_store_key = '/'.join((platform, api_name))
     jsc_model_future = self._model_cache.Get(object_store_key)
     model_future = self._platform_bundle.GetAPIModels(platform).GetModel(
         api_name)
     def resolve():
       jsc_model = jsc_model_future.Get()
       if jsc_model is None:
         jsc_model = _JSCModel(
             model_future.Get(),
-            self._platform_bundle.GetAvailabilityFinder(
-                platform).GetAPIAvailability(api_name),
+            self._platform_bundle.GetAvailabilityFinder(platform),
             self._json_cache,
             self._template_cache,
             self._platform_bundle.GetFeaturesBundle(platform),
             self._LoadEventByName(platform)).ToDict()
         self._model_cache.Set(object_store_key, jsc_model)
       return jsc_model
     return Future(callback=resolve)
 
   def _GetImpl(self, platform, api_name):
     handlebar_dict_future = self._GetSchemaModel(platform, api_name)
@@ skipping 15 matching lines @@
     getter = lambda: 0
     getter.get = lambda api_name: self._GetImpl(platform, api_name).Get()
     return getter
 
   def Cron(self):
     futures = []
     for platform in GetPlatforms():
       futures += [self._GetImpl(platform, name)
           for name in self._platform_bundle.GetAPIModels(platform).GetNames()]
     return Collect(futures, except_pass=FileNotFoundError)