list apis by channel info, e.g. dev, stable

chrome/common/extensions/docs/server2/api_list_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 operator import itemgetter
 import os
 import posixpath
 
+from branch_utility import ChannelInfo
 from svn_constants import PUBLIC_TEMPLATE_PATH
 import docs_server_utils as utils
+from file_system import FileNotFoundError
 
-def _GetAPICategory(api, documented_apis):
-  name = api['name']
-  if (name.endswith('Private') or
-      name not in documented_apis):
+def _GetAPICategory(api_name, documented_apis):
+  if (api_name.endswith('Private') or
+      api_name not in documented_apis):
     return 'private'
-  if name.startswith('experimental.'):
+  if api_name.startswith('experimental.'):
     return 'experimental'
   return 'chrome'
 
 
 class APIListDataSource(object):
   """ This class creates a list of chrome.* APIs and chrome.experimental.* APIs
   for extensions and apps that are used in the api_index.html,
   experimental.html, and private_apis.html pages.
 
   An API is considered listable if it is listed in _api_features.json,
   it has a corresponding HTML file in the public template path, and one of
   the following conditions is met:
     - It has no "dependencies" or "extension_types" properties in _api_features
     - It has an "extension_types" property in _api_features with either/both
       "extension"/"platform_app" values present.
     - It has a dependency in _{api,manifest,permission}_features with an
       "extension_types" property where either/both "extension"/"platform_app"
       values are present.
   """
   class Factory(object):
     def __init__(self,
                  compiled_fs_factory,
                  file_system,
                  features_bundle,
-                 object_store_creator):
+                 object_store_creator,
+                 api_models,
+                 availability_finder):
       self._file_system = file_system
       self._cache = compiled_fs_factory.Create(file_system,
                                                self._CollectDocumentedAPIs,
                                                APIListDataSource)
       self._features_bundle = features_bundle
       self._object_store_creator = object_store_creator
+      self._api_models = api_models
+      self._availability_finder = availability_finder
+
+    def _GetDocumentedApis(self):
+      return self._cache.GetFromFileListing(self._public_template_path).Get()
 
     def _CollectDocumentedAPIs(self, base_dir, files):
       def GetDocumentedAPIsForPlatform(names, platform):
         public_templates = []
         for root, _, files in self._file_system.Walk(posixpath.join(
             PUBLIC_TEMPLATE_PATH, platform)):
           public_templates.extend(
               ('%s/%s' % (root, name)).lstrip('/') for name in files)
         template_names = set(os.path.splitext(name)[0]
                              for name in public_templates)
         return [name.replace('_', '.') for name in template_names]
       api_names = set(utils.SanitizeAPIName(name) for name in files)
       return {
         'apps': GetDocumentedAPIsForPlatform(api_names, 'apps'),
         'extensions': GetDocumentedAPIsForPlatform(api_names, 'extensions')
       }
 
     def _GenerateAPIDict(self):
       documented_apis = self._cache.GetFromFileListing(
           PUBLIC_TEMPLATE_PATH).Get()
-      api_features = self._features_bundle.GetAPIFeatures().Get()
 
-      def FilterAPIs(platform):
-        return (api for api in api_features.itervalues()
-            if platform in api['platforms'])
+      def FilterAPIs():
+        return (api for api
+                in self._features_bundle.GetAPIFeatures().Get().itervalues()
+                if api['name'] in self._api_models.GetNames())
+
+      def GetChannelInfo(api_name):
+        return self._availability_finder.GetApiAvailability(api_name)
+
+      def GetApiDescription(api_name):
+        try:
+          model = self._api_models.GetModel(api_name).Get()
+          return model.description if model else ''
+        except FileNotFoundError:
+          return ''
 
       def MakeDictForPlatform(platform):
-        platform_dict = { 'chrome': [], 'experimental': [], 'private': [] }
-        for api in FilterAPIs(platform):
-          if api['name'] in documented_apis[platform]:
-            category = _GetAPICategory(api, documented_apis[platform])
-            platform_dict[category].append(api)
-        for category, apis in platform_dict.iteritems():
-          platform_dict[category] = sorted(apis, key=itemgetter('name'))
-          utils.MarkLast(platform_dict[category])
+        platform_dict = {
+          'chrome': {'stable': [], 'beta': [], 'dev': [], 'trunk': []}
+        }
+        private_apis = []
+        experimental_apis = []
+        all_apis = []
+
+        for api in FilterAPIs():
+          api_name = api['name']
+          category = _GetAPICategory(api_name, documented_apis[platform])
+          api['description'] = GetApiDescription(api_name)

[not at google - send to devlin, 2013/11/11 15:58:04]

This and below is modifying the live data returned by GetAPIFeatures(), which is
bad; a side-effect of calling this method. You should construct a new object to
pass to the model with just the specific data that you need.

api_data = {
  'name': api['name'],
  ...
}
...
all_apis.append(api_data)

Sorry for not noticing this earlier. It's also why I didn't notice that you were
using the platform etc data straight from the feature object.

Still, please loop over the result from api_list.GetNames() not the features.
It's idiomatically correct. If you need feature data like the platform then grab
the feature separately:

for api_name in self._api_models.GetNames():
  api_model = self._api_models.GetModel(api_name)
  api_feature = self._features_bundle.GetAPIFeatures()[api_name]
  ...

You might actually want to add an APIModels.IterModels() which yields (name,
model) pairs so that you can write

for api_name, api_model in self._api_models.IterModels():
  ...

[hukun, 2013/11/13 15:36:44]

Got it. If you do not mind, I fix it in next CL.

[not at google - send to devlin, 2013/11/13 15:49:56]

Please fix it now, it's a pretty small change. It's one thing to follow up with
a fix for unrelated code (that's fine) but don't submit code that you're just
going to change again right away.

[hukun, 2013/11/13 17:41:29]

Done. Fix it by using api_models.

+          if category == 'chrome':
+            channel_info = GetChannelInfo(api_name)
+            channel = channel_info.channel
+            if channel == 'stable':
+              api['version'] = channel_info.version
+            platform_dict[category][channel].append(api)
+            all_apis.append(api)
+          elif category == 'experimental':
+            experimental_apis.append(api)
+            all_apis.append(api)
+          elif category == 'private':
+            private_apis.append(api)
+
+        for channel, apis_by_channel in platform_dict['chrome'].iteritems():
+          apis_by_channel = sorted(apis_by_channel, key=itemgetter('name'))
+          utils.MarkLast(apis_by_channel)
+          platform_dict['chrome'][channel] = apis_by_channel
+
+        for key, apis in (('all', all_apis),
+                          ('private', private_apis),
+                          ('experimental', experimental_apis)):
+          apis = sorted(apis, key=itemgetter('name'))
+          utils.MarkLast(apis)
+          platform_dict[key] = apis
         return platform_dict
-
       return {
         'apps': MakeDictForPlatform('apps'),
-        'extensions': MakeDictForPlatform('extensions')
+        'extensions': MakeDictForPlatform('extensions'),
       }
 
     def Create(self):
       return APIListDataSource(self, self._object_store_creator)
 
   def __init__(self, factory, object_store_creator):
     self._factory = factory
     self._object_store = object_store_creator.Create(APIListDataSource)
 
   def _GetCachedAPIData(self):
     data = self._object_store.Get('api_data').Get()
     if data is None:
       data = self._factory._GenerateAPIDict()
       self._object_store.Set('api_data', data)
     return data
 
   def get(self, key):
     return self._GetCachedAPIData().get(key)