Docserver: Add more support for object level availability in templates

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 109 matching lines @@
         assert self._lookup_path[-3] == 'events'
         return self._lookup_path[:-1]
       # This is a function parameter.
       assert self._lookup_path[-2] == 'parameters'
       return self._lookup_path[:-2]
     # This is a regular node, so lookup_path[-2] should
     # be a node category.
     self._AssertIsValidCategory(self._lookup_path[-2])
     return self._lookup_path[:-2]
 
-  def _LookupNodeAvailability(self):
+  def _LookupNodeAvailability(self, lookup_path):
     '''Returns the ChannelInfo object for this node.
     '''
     return self._node_availabilities.Lookup(self._namespace_name,
-                                            *self._lookup_path).annotation
+                                            *lookup_path).annotation
 
   def _LookupParentNodeAvailability(self):
     '''Returns the ChannelInfo object for this node's parent.
     '''
-    return self._node_availabilities.Lookup(self._namespace_name,
-                                            *self._GetParentPath()).annotation
+    return self._LookupNodeAvailability(self._GetParentPath())

[not at google - send to devlin, 2014/07/02 22:14:34]

could you make a bunch of these @classmethod-s to avoid the temptation of using
self._lookup_path by accident, if possible?

[ahernandez, 2014/07/02 22:25:47]

I don't understand what you mean.

[ahernandez, 2014/07/02 22:27:22]

Actually, my confusion has ended.

 
-  def _CheckNamespacePrefix(self):
+  def _CheckNamespacePrefix(self, lookup_path):
     '''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 node category (e.g. types, functions, etc.).
     # Thus, lookup_path[1] is always the top-level node name.
-    self._AssertIsValidCategory(self._lookup_path[0])
-    base_name = self._lookup_path[1]
-    self._lookup_path[1] = '%s.%s' % (self._namespace_name, base_name)
+    self._AssertIsValidCategory(lookup_path[0])
+    base_name = lookup_path[1]
+    lookup_path[1] = '%s.%s' % (self._namespace_name, base_name)
     try:
-      node_availability = self._LookupNodeAvailability()
+      node_availability = self._LookupNodeAvailability(lookup_path)
       if node_availability is not None:
         return node_availability
     finally:
       # Restore lookup_path.
-      self._lookup_path[1] = base_name
+      lookup_path[1] = base_name
     return None
 
-  def _CheckEventCallback(self):
+  def _CheckEventCallback(self, lookup_path):
     '''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:
-      assert 'callback' in self._lookup_path
-      callback_index = self._lookup_path.index('callback')
+    if 'events' in lookup_path:
+      assert 'callback' in lookup_path
+      callback_index = lookup_path.index('callback')
       try:
-        self._lookup_path.pop(callback_index)
-        node_availability = self._LookupNodeAvailability()
+        lookup_path.pop(callback_index)
+        node_availability = self._LookupNodeAvailability(lookup_path)
       finally:
-        self._lookup_path.insert(callback_index, 'callback')
+        lookup_path.insert(callback_index, 'callback')
       return node_availability
     return None
 
-  def _LookupAvailability(self):
+  def _LookupAvailability(self, lookup_path):
     '''Runs all the lookup checks on self._lookup_path and
     returns the node availability if found, None otherwise.
     '''
     for lookup in (self._LookupNodeAvailability,
                    self._CheckEventCallback,
                    self._CheckNamespacePrefix):
-      node_availability = lookup()
+      node_availability = lookup(lookup_path)
       if node_availability is not None:
         return node_availability
     return None
 
   def GetAvailability(self):
     '''Returns availability information for this node.
     '''
-    node_availability = self._LookupAvailability()
+    node_availability = self._LookupAvailability(self._lookup_path)
     if node_availability is None:
       logging.warning('No availability found for: %s > %s' %
           (self._namespace_name, ' > '.join(self._lookup_path)))
       return None
 
-    try:
-      current_path = self._lookup_path
-      self._lookup_path = self._GetParentPath()
-      parent_node_availability = self._LookupAvailability()
-    finally:
-      self._lookup_path = current_path
+    parent_node_availability = self._LookupAvailability(self._GetParentPath())
     # If the parent node availability couldn't be found, something
     # is very wrong.
     assert parent_node_availability is not None
 
     # Only render this node's availability if it differs from the parent
     # node's availability.
     if node_availability == parent_node_availability:
       return None
     return node_availability
 
@@ skipping 63 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):
+  def _GenerateTypes(self, types, no_gen=False):
     with self._current_node.Descend('types'):
-      return [self._GenerateType(t) for t in types]
+      return [self._GenerateType(t, no_gen=no_gen) for t in types]
 
-  def _GenerateType(self, type_):
+  def _GenerateType(self, type_, no_gen=False):
     with self._current_node.Descend(type_.simple_name):
       type_dict = {
         'name': type_.simple_name,
         'description': type_.description,
-        'properties': self._GenerateProperties(type_.properties),
+        'properties': self._GenerateProperties(type_.properties, no_gen=no_gen),

[ahernandez, 2014/07/03 02:04:14]

I think eliminating the no_gen passing will make the code more awkward in
another way. On the line this comment is on, if we don't want availability data
generated for properties, we still want to generate it for functions, but if
no_gen is set to true while in the scope then the availability data won't be
generated. A possible solution is to say something like 'with
self._current_node.Descend('', no_gen=False)' where we need availability data
generated, but it seems like having to do that in certain places will be just as
noisy. WDYT?

[not at google - send to devlin, 2014/07/07 15:10:31]

What about if no_gen took a tuple of properties to disable generation for
(no_gen=('properties')), or even just a string? Is that also too simplistic?

[ahernandez, 2014/07/07 20:04:56]

Doing that cleans up a good portion of the code, but there are still a few weird
spots where I have to call Descend() without specifying a path to descend to,
just so that a node will not have availability generated for it.

         'functions': self._GenerateFunctions(type_.functions),
         'events': self._GenerateEvents(type_.events),
         'id': _CreateId(type_, 'type'),
+        'availability': None if no_gen else self._GetAvailabilityTemplate()

[not at google - send to devlin, 2014/07/02 22:14:34]

why do you need to do this no_gen stuff?

in any case, passing no_gen around everywhere is pretty noisy. could you
incorporate that state into |current_node| somehow? scope the "no gen" to those
Descend calls?

[ahernandez, 2014/07/02 22:25:47]

Certain nodes shouldn't have availability generated; no_gen is the equivalent of
blank paths in Evan's original patch. Scoping the no_gen in Descend should work.

       }
       self._RenderTypeInformation(type_, type_dict)
       return type_dict
 
   def _GenerateFunctions(self, functions):
     with self._current_node.Descend('functions'):
       return [self._GenerateFunction(f) for f in functions.values()]
 
   def _GenerateFunction(self, function):
     with self._current_node.Descend(function.simple_name):
       function_dict = {
         'name': function.simple_name,
         'description': function.description,
         'callback': self._GenerateCallback(function.callback),
         'parameters': [],
         'returns': None,
         'id': _CreateId(function, 'method'),
         'availability': self._GetAvailabilityTemplate()
       }
       self._AddCommonProperties(function_dict, function)
       if function.returns:
-        function_dict['returns'] = self._GenerateType(function.returns)
-      for param in function.params:
-        function_dict['parameters'].append(self._GenerateProperty(param))
+        function_dict['returns'] = self._GenerateType(function.returns,
+                                                      no_gen=True)
+      with self._current_node.Descend('parameters'):
+        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
 
   def _GenerateEvents(self, events):
     with self._current_node.Descend('events'):
       return [self._GenerateEvent(e) for e in events.values()
               if not e.supports_dom]
 
   def _GenerateDomEvents(self, events):
     with self._current_node.Descend('events'):
       return [self._GenerateEvent(e) for e in events.values()
               if e.supports_dom]
 
   def _GenerateEvent(self, event):
     with self._current_node.Descend(event.simple_name):
       event_dict = {
         'name': event.simple_name,
         'description': event.description,
-        'filters': [self._GenerateProperty(f) for f in event.filters],
+        'filters': [self._GenerateProperty(f, no_gen=True)
+                    for f in event.filters],
         'conditions': [self._GetLink(condition)
                        for condition in event.conditions],
         'actions': [self._GetLink(action) for action in event.actions],
         'supportsRules': event.supports_rules,
         'supportsListeners': event.supports_listeners,
         'properties': [],
         'id': _CreateId(event, 'event'),
         'byName': {},
+        'availability': self._GetAvailabilityTemplate()
       }
       self._AddCommonProperties(event_dict, event)
       # Add the Event members to each event in this object.
       if self._event_byname_future:
         event_dict['byName'].update(self._event_byname_future.Get())
       # We need to create the method description for addListener based on the
       # information stored in |event|.
       if event.supports_listeners:
         callback_object = model.Function(parent=event,
                                          name='callback',
                                          json={},
                                          namespace=event.parent,
                                          origin='')
         callback_object.params = event.params
         if event.callback:
           callback_object.callback = event.callback
         callback_parameters = self._GenerateCallbackProperty(callback_object)
         callback_parameters['last'] = True
         event_dict['byName']['addListener'] = {
           'name': 'addListener',
           'callback': self._GenerateFunction(callback_object),
           'parameters': [callback_parameters]
         }
       if event.supports_dom:
         # Treat params as properties of the custom Event object associated with
         # this DOM Event.
-        event_dict['properties'] += [self._GenerateProperty(param)
+        event_dict['properties'] += [self._GenerateProperty(param, no_gen=True)
                                      for param in event.params]
       return event_dict
 
   def _GenerateCallback(self, callback):
     if not callback:
       return None
     callback_dict = {
       'name': callback.simple_name,
       'simple_type': {'simple_type': 'function'},
       'optional': callback.optional,
       'parameters': []
     }
-    for param in callback.params:
-      callback_dict['parameters'].append(self._GenerateProperty(param))
+    with self._current_node.Descend('parameters',
+                                    callback.simple_name,
+                                    'parameters'):
+      for param in callback.params:
+        callback_dict['parameters'].append(self._GenerateProperty(param))
     if (len(callback_dict['parameters']) > 0):
       callback_dict['parameters'][-1]['last'] = True
     return callback_dict
 
-  def _GenerateProperties(self, properties):
-    return [self._GenerateProperty(v) for v in properties.values()]
+  def _GenerateProperties(self, properties, no_gen=False):
+    with self._current_node.Descend('properties'):
+      return [self._GenerateProperty(v, no_gen=no_gen)
+              for v in properties.values()]
 
-  def _GenerateProperty(self, property_):
-    if not hasattr(property_, 'type_'):
-      for d in dir(property_):
-        if not d.startswith('_'):
-          print ('%s -> %s' % (d, getattr(property_, d)))
-    type_ = property_.type_
+  def _GenerateProperty(self, property_, no_gen=False):
+    with self._current_node.Descend(property_.simple_name):
+      if not hasattr(property_, 'type_'):
+        for d in dir(property_):
+          if not d.startswith('_'):
+            print ('%s -> %s' % (d, getattr(property_, d)))
+      type_ = property_.type_
 
-    # Make sure we generate property info for arrays, too.
-    # TODO(kalman): what about choices?
-    if type_.property_type == model.PropertyType.ARRAY:
-      properties = type_.item_type.properties
-    else:
-      properties = type_.properties
+      # Make sure we generate property info for arrays, too.
+      # TODO(kalman): what about choices?
+      if type_.property_type == model.PropertyType.ARRAY:
+        properties = type_.item_type.properties
+      else:
+        properties = type_.properties
 
-    property_dict = {
-      'name': property_.simple_name,
-      'optional': property_.optional,
-      'description': property_.description,
-      'properties': self._GenerateProperties(type_.properties),
-      'functions': self._GenerateFunctions(type_.functions),
-      'parameters': [],
-      'returns': None,
-      'id': _CreateId(property_, 'property'),
-    }
-    self._AddCommonProperties(property_dict, property_)
+      property_dict = {
+        'name': property_.simple_name,
+        'optional': property_.optional,
+        'description': property_.description,
+        'properties': self._GenerateProperties(type_.properties, no_gen=True),
+        'functions': self._GenerateFunctions(type_.functions),
+        'parameters': [],
+        'returns': None,
+        'id': _CreateId(property_, 'property'),
+        'availability': None if no_gen else self._GetAvailabilityTemplate()
+      }
+      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)
+      if type_.property_type == model.PropertyType.FUNCTION:
+        function = type_.function
+        with self._current_node.Descend('parameters'):
+          for param in function.params:
+            property_dict['parameters'].append(self._GenerateProperty(param))
+        if 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)
+      value = property_.value
+      if value is not None:
+        if isinstance(value, int):
+          property_dict['value'] = _FormatValue(value)
+        else:
+          property_dict['value'] = value
       else:
-        property_dict['value'] = value
-    else:
-      self._RenderTypeInformation(type_, property_dict)
+        self._RenderTypeInformation(type_, property_dict)
 
-    return 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 231 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)