Linking AvailabilityFinder with APIDataSource and intro-table templates.

chrome/common/extensions/docs/server2/availability_finder.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.
 
 import collections
 import os
 
 from branch_utility import BranchUtility
 from compiled_file_system import CompiledFileSystem
 from file_system import FileNotFoundError
 import svn_constants
 from third_party.json_schema_compiler import json_parse, model
 from third_party.json_schema_compiler.memoize import memoize
 
 _API_AVAILABILITIES = svn_constants.JSON_PATH + '/api_availabilities.json'
 _API_FEATURES = svn_constants.API_PATH + '/_api_features.json'
 _EXTENSION_API = svn_constants.API_PATH + '/extension_api.json'
 _MANIFEST_FEATURES = svn_constants.API_PATH + '/_manifest_features.json'
 _PERMISSION_FEATURES = svn_constants.API_PATH + '/_permission_features.json'
 _STABLE = 'stable'
 
+_EXPERIMENTAL_MESSAGE = ('Experimental only (see' +
+    '<a href="experimental.html#using">How to use experimental APIs</a>).')

[not at google - send to devlin, 2013/07/09 23:11:55]

ah. so maybe we need to actually pass _templates_ into that table? definitely
can't be embedding HTML in the server code.

so like, allow passing a 'partial' argument as well (like 'text'), then the
intro content would look something like

{{?link ... }}
{{?class ... }}
{{?text text /}}
{{?partial +partial /}}
{{?class...}}
{{?link ...}}

[epeterson, 2013/07/16 00:28:23]

Solution to this no longer involves availability_finder for HTML, which is good.
The logic is over in api_data_source.

+
 class AvailabilityInfo(object):
   def __init__(self, channel, version):
     self.channel = channel
     self.version = version
 
 def _GetChannelFromFeatures(api_name, file_system, path):
   '''Finds API channel information within _features.json files at the given
   |path| for the given |file_system|. Returns None if channel information for
   the API cannot be located.
   '''
   feature = file_system.GetFromFile(path).get(api_name)
 
   if feature is None:
     return None
   if isinstance(feature, collections.Mapping):
     # The channel information dict is nested within a list for whitelisting
     # purposes.
     return feature.get('channel')
   # Features can contain a list of entries. Take the newest branch.
   return BranchUtility.NewestChannel(entry.get('channel')
                                      for entry in feature)
 
 def _GetChannelFromApiFeatures(api_name, file_system):
   try:
     return _GetChannelFromFeatures(api_name, file_system, _API_FEATURES)
-  except FileNotFoundError as e:
+  except FileNotFoundError:
     # TODO(epeterson) Remove except block once _api_features is in all channels.
     return None
 
 def _GetChannelFromPermissionFeatures(api_name, file_system):
   return _GetChannelFromFeatures(api_name, file_system, _PERMISSION_FEATURES)
 
 def _GetChannelFromManifestFeatures(api_name, file_system):
   return _GetChannelFromFeatures(#_manifest_features uses unix_style API names
                                  model.UnixName(api_name),
                                  file_system,
@@ skipping 10 matching lines @@
 def _ExistsInExtensionApi(api_name, file_system):
   '''Parses the api/extension_api.json file (available in Chrome versions
   before 18) for an API namespace. If this is successfully found, then the API
   is considered to have been 'stable' for the given version.
   '''
   try:
     extension_api_json = file_system.GetFromFile(_EXTENSION_API)
     api_rows = [row.get('namespace') for row in extension_api_json
                 if 'namespace' in row]
     return True if api_name in api_rows else False
-  except FileNotFoundError as e:
+  except FileNotFoundError:
     # This should only happen on preview.py since extension_api.json is no
     # longer present in trunk.
     return False
 
 class AvailabilityFinder(object):
   '''Uses API data sources generated by a ChromeVersionDataSource in order to
   search the filesystem for the earliest existence of a specified API throughout
   the different versions of Chrome; this constitutes an API's availability.
   '''
   class Factory(object):
@@ skipping 57 matching lines @@
     on the stable channel. When a version is found where the API is no longer
     available on stable, returns the previous version number (the last known
     version where the API was stable).
     '''
     available = True
     while available:
       if version < 5:
         # SVN data isn't available below version 5.
         return version + 1
       available = False
+      available_channel = None
       features_fs, names_fs = self._CreateFeaturesAndNamesFileSystems(version)
       if version >= 28:
         # The _api_features.json file first appears in version 28 and should be
         # the most reliable for finding API availabilities, so it gets checked
         # first. The _permission_features.json and _manifest_features.json files
         # are present in Chrome 20 and onwards. Fall back to a check for file
         # system existence if the API is not stable in any of the _features.json
         # files.
-        available = _GetChannelFromApiFeatures(api_name, features_fs) == _STABLE
+        available_channel = _GetChannelFromApiFeatures(api_name, features_fs)
       if version >= 20:
         # Check other _features.json files/file existence if the API wasn't
         # found in _api_features.json, or if _api_features.json wasn't present.
-        available = available or (
-            _GetChannelFromPermissionFeatures(api_name, features_fs) == _STABLE
-            or _GetChannelFromManifestFeatures(api_name, features_fs) == _STABLE
-            or _ExistsInFileSystem(api_name, names_fs))
+        available_channel = available_channel or (
+            _GetChannelFromPermissionFeatures(api_name, features_fs)
+            or _GetChannelFromManifestFeatures(api_name, features_fs))
+        if available_channel is None:
+          available = _ExistsInFileSystem(api_name, names_fs)
+        else:
+          available = available_channel == _STABLE
       elif version >= 18:
         # These versions are a little troublesome. Version 19 has
         # _permission_features.json, but it lacks 'channel' information.
         # Version 18 lacks all of the _features.json files. For now, we're using
         # a simple check for filesystem existence here.
         available = _ExistsInFileSystem(api_name, names_fs)
       elif version >= 5:
         # Versions 17 and down to 5 have an extension_api.json file which
         # contains namespaces for each API that was available at the time. We
         # can use this file to check for API existence.
         available = _ExistsInExtensionApi(api_name, features_fs)
 
       if not available:
         return version + 1
       version -= 1
 
   def _GetAvailableChannelForVersion(self, api_name, version):
     '''Searches through the _features files for a given |version| and returns
     the channel that the given API is determined to be available on.
     '''
     features_fs, names_fs = self._CreateFeaturesAndNamesFileSystems(version)
-    channel = (_GetChannelFromApiFeatures(api_name, features_fs)
-               or _GetChannelFromPermissionFeatures(api_name, features_fs)
-               or _GetChannelFromManifestFeatures(api_name, features_fs))
-    if channel is None and _ExistsInFileSystem(api_name, names_fs):
+    available_channel = (_GetChannelFromApiFeatures(api_name, features_fs)
+        or _GetChannelFromPermissionFeatures(api_name, features_fs)
+        or _GetChannelFromManifestFeatures(api_name, features_fs))
+    if available_channel is None and _ExistsInFileSystem(api_name, names_fs):
       # If an API is not represented in any of the _features files, but exists
       # in the filesystem, then assume it is available in this version.
       # The windows API is an example of this.
       return self._branch_utility.GetChannelForVersion(version)
 
-    return channel
+    return available_channel
 
   def GetApiAvailability(self, api_name):
     '''Determines the availability for an API by testing several scenarios.
     (i.e. Is the API experimental? Only available on certain development
     channels? If it's stable, when did it first become stable? etc.)
     '''
     availability = self._object_store.Get(api_name).Get()
     if availability is not None:
       return availability
 
@@ skipping 25 matching lines @@
 
     # If the API is in stable, find the chrome version in which it became
     # stable.
     if availability.channel == _STABLE:
       availability.version = self._FindEarliestStableAvailability(
           api_name,
           availability.version)
 
     self._object_store.Set(api_name, availability)
     return availability
+
+  @staticmethod
+  def StringifyAvailability(availability):
+    '''Given an AvailabilityInfo struct, provides a message that can be
+    displayed in an API intro table
+    '''
+    availability_id = 'intro-availability'
+    if availability.channel == 'stable':
+      return '<span id="%s" class="%s">Stable</span> since version %s.' % (
+          availability_id, availability.channel, availability.version)
+    else:
+      return 'Available on <span id="%s" class="%s">%s</span>.' % (
+          availability_id, availability.channel, availability.channel)

[not at google - send to devlin, 2013/07/09 23:11:55]

Yeah ok so same thing with the partials. We'll need to to some tweaking of the
language. Maybe for the beta version it shlud be

"<a ...>Beta and dev channels</a> only"

dev

"<a...>Dev channel</a> only"

trunk

"Only when <a>built from source</a>"

and we can add the same links there that we already have for the warnings.

oh and, the screenshots look awesome but it makes me realise that the colours
there are actually really confusing, so let's give up on that avenue :( sorry.

[epeterson, 2013/07/16 00:28:23]

Done.