Linking AvailabilityFinder with APIDataSource and intro-table 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.
 
 import copy
 import logging
 import os
 from collections import defaultdict, Mapping
 
+from branch_utility import BranchUtility
+import svn_constants
 import third_party.json_schema_compiler.json_parse as json_parse
 import third_party.json_schema_compiler.model as model
 import third_party.json_schema_compiler.idl_schema as idl_schema
 import third_party.json_schema_compiler.idl_parser as idl_parser
 
 def _RemoveNoDocs(item):
   if json_parse.IsDict(item):
     if item.get('nodoc', False):
       return True
     for key, value in item.items():
@@ skipping 76 matching lines @@
 def _FormatValue(value):
   """Inserts commas every three digits for integer values. It is magic.
   """
   s = str(value)
   return ','.join([s[max(0, i - 3):i] for i in range(len(s), 0, -3)][::-1])
 
 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, json, ref_resolver, disable_refs, idl=False):
+  def __init__(self,
+               json,
+               ref_resolver,
+               disable_refs,
+               availability_finder,
+               intro_cache,
+               template_data_source,
+               idl=False):
     self._ref_resolver = ref_resolver
     self._disable_refs = disable_refs
+    self._availability_finder = availability_finder
+    self._intro_tables = intro_cache.GetFromFile(
+        '%s/intro_tables.json' % svn_constants.JSON_PATH)
+    self._template_data_source = template_data_source
     clean_json = copy.deepcopy(json)
     if _RemoveNoDocs(clean_json):
       self._namespace = None
     else:
       if idl:
         _DetectInlineableTypes(clean_json)
       _InlineDocs(clean_json)
       self._namespace = model.Namespace(clean_json, clean_json['namespace'])
 
   def _FormatDescription(self, description):
     if self._disable_refs:
       return description
     return self._ref_resolver.ResolveAllLinks(description,
                                               namespace=self._namespace.name)
 
   def _GetLink(self, link):
     if self._disable_refs:
       type_name = link.split('.', 1)[-1]
       return { 'href': '#type-%s' % type_name, 'text': link, 'name': link }
     return self._ref_resolver.SafeGetLink(link, namespace=self._namespace.name)
 
   def ToDict(self):
     if self._namespace is None:
       return {}
     return {
       'name': self._namespace.name,
-      'description': self._namespace.description,
       'types': self._GenerateTypes(self._namespace.types.values()),
       'functions': self._GenerateFunctions(self._namespace.functions),
       'events': self._GenerateEvents(self._namespace.events),
-      'properties': self._GenerateProperties(self._namespace.properties)
+      'properties': self._GenerateProperties(self._namespace.properties),
+      'intro_list': self._GetIntroTableList()
     }
 
+  def _GetIntroTableList(self):
+    """Create a generic data structure that can be traversed by the templates
+    to create an API intro table.
+    """
+    intro_list = [{
+      'title': 'Description',
+      'content': [
+        { 'text': self._FormatDescription(self._namespace.description) }
+      ]
+    }]
+
+    if self._IsExperimental():
+      status = 'experimental'
+      version = None
+    else:
+      availability = self._GetApiAvailability()
+      status = availability.channel
+      version = availability.version
+    intro_list.append({
+      'title': 'Availability',
+      'content': [
+        {
+          'partial': self._template_data_source.get(
+              'intro_tables/%s_message.html' % status),
+          'version': version
+        }
+      ]
+    })
+
+    # Look up the API name in intro_tables.json, which is structured similarly
+    # to the data structure being created. If the name is found, loop through
+    # the attributes and add them to this structure.
+    table_info = self._intro_tables.get(self._namespace.name)
+    if table_info is None:
+      return intro_list
+
+    # The intro tables have a specific ordering that needs to be followed.
+    ordering = ('Permissions', 'Samples', 'Learn More')
+
+    for category in ordering:
+      if category not in table_info.keys():
+        continue
+      # Transform the 'partial' argument from the partial name to the
+      # template itself.
+      content = table_info[category]
+      for node in content:
+        # If there is a 'partial' argument and it hasn't already been
+        # converted, transform it to a template.
+        if 'partial' in node and isinstance (node['partial'], basestring):

[epeterson, 2013/07/18 18:17:07]

Similar to the isinstance(.. Handlebar) check, though perhaps clearer with the
added comment?

If this check isn't here, then the 'partial' argument can be fetched again,
which throws an error (Handlebar object has no .endswith() method for
.endswith('html')) since it's no longer a string to look up.

An alternative would be to mutate the dict and add a separate argument with the
Handlebar data, like 'template', and not directly mutation the 'partial'
argument's data.

[not at google - send to devlin, 2013/07/18 21:24:15]

Oh so it shouldn't be computing this more than once because it's supposed to be
caching the result of ToDict. This method is only called for ToDict and ToDict
is only called from within callbacks of a CompiledFileSystem...

[epeterson, 2013/07/19 00:05:35]

Added a TODO, but I'm curious as to what I may have done that stopped this from
caching properly... or if it's been that way? (hopefully not)

+          node['partial'] = self._template_data_source.get(node['partial'])
+      intro_list.append({
+        'title': category,
+        'content': content
+      })
+    return intro_list
+
+  def _GetApiAvailability(self):
+    return self._availability_finder.GetApiAvailability(self._namespace.name)
+
+  def _IsExperimental(self):
+     return self._namespace.name.startswith('experimental')
+
   def _GenerateTypes(self, types):
     return [self._GenerateType(t) for t in types]
 
   def _GenerateType(self, type_):
     type_dict = {
       'name': type_.simple_name,
       'description': self._FormatDescription(type_.description),
       'properties': self._GenerateProperties(type_.properties),
       'functions': self._GenerateFunctions(type_.functions),
       'events': self._GenerateEvents(type_.events),
@@ skipping 166 matching lines @@
     self._samples = samples
 
   def get(self, key):
     return self._samples.FilterSamples(key, self._api_name)
 
 class APIDataSource(object):
   """This class fetches and loads JSON APIs from the FileSystem passed in with
   |compiled_fs_factory|, so the APIs can be plugged into templates.
   """
   class Factory(object):
-    def __init__(self, compiled_fs_factory, base_path):
+    def __init__(self,
+                 compiled_fs_factory,
+                 base_path,
+                 availability_finder_factory):
       def create_compiled_fs(fn, category):
         return compiled_fs_factory.Create(fn, APIDataSource, category=category)
 
       self._permissions_cache = create_compiled_fs(self._LoadPermissions,
                                                    'permissions')
 
       self._json_cache = create_compiled_fs(
           lambda api_name, api: self._LoadJsonAPI(api, False),
           'json')
       self._idl_cache = create_compiled_fs(
           lambda api_name, api: self._LoadIdlAPI(api, False),
           'idl')
 
       # These caches are used if an APIDataSource does not want to resolve the
       # $refs in an API. This is needed to prevent infinite recursion in
       # ReferenceResolver.
       self._json_cache_no_refs = create_compiled_fs(
           lambda api_name, api: self._LoadJsonAPI(api, True),
           'json-no-refs')
       self._idl_cache_no_refs = create_compiled_fs(
           lambda api_name, api: self._LoadIdlAPI(api, True),
           'idl-no-refs')
 
       self._idl_names_cache = create_compiled_fs(self._GetIDLNames, 'idl-names')
       self._names_cache = create_compiled_fs(self._GetAllNames, 'names')
 
       self._base_path = base_path
-
+      self._availability_finder = availability_finder_factory.Create()
+      self._intro_cache = create_compiled_fs(
+          lambda _, json: json_parse.Parse(json),
+          'intro-cache')
       # These must be set later via the SetFooDataSourceFactory methods.
       self._ref_resolver_factory = None
       self._samples_data_source_factory = None
 
     def SetSamplesDataSourceFactory(self, samples_data_source_factory):
       self._samples_data_source_factory = samples_data_source_factory
 
     def SetReferenceResolverFactory(self, ref_resolver_factory):
       self._ref_resolver_factory = ref_resolver_factory
 
+    def SetTemplateDataSource(self, template_data_source_factory):
+      # This TemplateDataSource is only being used for fetching template data.
+      self._template_data_source = template_data_source_factory.Create(None, '')

[epeterson, 2013/07/18 18:17:07]

No request or path data is given here, since this template data source doesn't
need the information for getting template data. (Also, I'm not sure how I would
magick up a request and path here)

Creating just one template data source here instead of setting a factory and
passing that factory to JSCModel and having it create tons of template data
sources.

[not at google - send to devlin, 2013/07/18 21:24:15]

Ah ok. That's fine for now. I will try to refactor things a bit here to have
more sensible dependencies.

+
     def Create(self, request, disable_refs=False):
       """Create an APIDataSource. |disable_refs| specifies whether $ref's in
       APIs being processed by the |ToDict| method of _JSCModel follows $ref's
       in the API. This prevents endless recursion in ReferenceResolver.
       """
       if self._samples_data_source_factory is None:
         # Only error if there is a request, which means this APIDataSource is
         # actually being used to render a page.
         if request is not None:
           logging.error('SamplesDataSource.Factory was never set in '
@@ skipping 15 matching lines @@
                            samples,
                            disable_refs)
 
     def _LoadPermissions(self, file_name, json_str):
       return json_parse.Parse(json_str)
 
     def _LoadJsonAPI(self, api, disable_refs):
       return _JSCModel(
           json_parse.Parse(api)[0],
           self._ref_resolver_factory.Create() if not disable_refs else None,
-          disable_refs).ToDict()
+          disable_refs,
+          self._availability_finder,
+          self._intro_cache,
+          self._template_data_source).ToDict()
 
     def _LoadIdlAPI(self, api, disable_refs):
       idl = idl_parser.IDLParser().ParseData(api)
       return _JSCModel(
           idl_schema.IDLSchema(idl).process()[0],
           self._ref_resolver_factory.Create() if not disable_refs else None,
           disable_refs,
+          self._availability_finder,
+          self._intro_cache,
+          self._template_data_source,
           idl=True).ToDict()
 
     def _GetIDLNames(self, base_dir, apis):
       return self._GetExtNames(apis, ['idl'])
 
     def _GetAllNames(self, base_dir, apis):
       return self._GetExtNames(apis, ['json', 'idl'])
 
     def _GetExtNames(self, apis, exts):
       return [model.UnixName(os.path.splitext(api)[0]) for api in apis
@@ skipping 48 matching lines @@
         if feature_data is not None:
           # Note: if you are seeing the exception below, add more heuristics as
           # required to form a single feature.
           raise ValueError('Multiple potential features match %s. I can\'t '
                            'decide which one to use. Please help!' % path)
         feature_data = single_feature
 
     if feature_data and feature_data['channel'] in ('trunk', 'dev', 'beta'):
       feature_data[feature_data['channel']] = True
     return feature_data
 

[epeterson, 2013/07/19 00:05:35]

This stuff is gone, it was only used for the warning bar.

   def _GenerateHandlebarContext(self, handlebar_dict, path):
     handlebar_dict['permissions'] = self._GetFeatureData(path)
     handlebar_dict['samples'] = _LazySamplesGetter(path, self._samples)
     return handlebar_dict
 
   def _GetAsSubdirectory(self, name):
     if name.startswith('experimental_'):
       parts = name[len('experimental_'):].split('_', 1)
-      parts[1] = 'experimental_%s' % parts[1]
-      return '/'.join(parts)
+      if len(parts) > 1:
+        parts[1] = 'experimental_%s' % parts[1]
+        return '/'.join(parts)
+      return '%s/%s' % (parts[0], name)
     return name.replace('_', '/', 1)
 
   def get(self, key):
     if key.endswith('.html') or key.endswith('.json') or key.endswith('.idl'):
       path, ext = os.path.splitext(key)
     else:
       path = key
     unix_name = model.UnixName(path)
     idl_names = self._idl_names_cache.GetFromFileListing(self._base_path)
     names = self._names_cache.GetFromFileListing(self._base_path)
     if unix_name not in names and self._GetAsSubdirectory(unix_name) in names:
       unix_name = self._GetAsSubdirectory(unix_name)
 
     if self._disable_refs:
       cache, ext = (
           (self._idl_cache_no_refs, '.idl') if (unix_name in idl_names) else
           (self._json_cache_no_refs, '.json'))
     else:
       cache, ext = ((self._idl_cache, '.idl') if (unix_name in idl_names) else
                     (self._json_cache, '.json'))
     return self._GenerateHandlebarContext(
         cache.GetFromFile('%s/%s%s' % (self._base_path, unix_name, ext)),
         path)