docserver: Adds "API scheduled for Chrome version..." text to dev and beta APIs

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.
 
 from collections import Mapping
 import posixpath
 
 from api_schema_graph import APISchemaGraph
-from branch_utility import BranchUtility
+from branch_utility import BranchUtility, ChannelInfo
 from extensions_paths import API_PATHS, JSON_TEMPLATES
 from features_bundle import FeaturesBundle
 import features_utility
 from file_system import FileNotFoundError
 from third_party.json_schema_compiler.memoize import memoize
 from third_party.json_schema_compiler.model import UnixName
 
 
 _EXTENSION_API = 'extension_api.json'
 
 # The version where api_features.json is first available.
 _API_FEATURES_MIN_VERSION = 28
 # The version where permission_ and manifest_features.json are available and
 # presented in the current format.
 _ORIGINAL_FEATURES_MIN_VERSION = 20
 # API schemas are aggregated in extension_api.json up to this version.
 _EXTENSION_API_MAX_VERSION = 17
 # The earliest version for which we have SVN data.
 _SVN_MIN_VERSION = 5
 
 
 def _GetChannelFromFeatures(api_name, features):
   '''Finds API channel information for |api_name| from |features|.
   Returns None if channel information for the API cannot be located.
   '''
   feature = features.Get().get(api_name)
   return feature.get('channel') if feature else None
 
 
+class AvailabilityInfo(object):
+  '''Represents availability data for an API. |scheduled| is a version number
+  specifying when dev and beta APIs will become stable, or None if that data
+  is unknown.
+  '''
+  def __init__(self, channel_info, scheduled=None):
+    assert isinstance(channel_info, ChannelInfo)
+    assert isinstance(scheduled, int) or scheduled is None
+    self.channel_info = channel_info
+    self.scheduled = scheduled
+
+  def __eq__(self, other):
+    return self.__dict__ == other.__dict__
+
+  def __ne__(self, other):
+    return not (self == other)
+
+  def __repr__(self):
+    return '%s%s' % (type(self).__name__, repr(self.__dict__))
+
+  def __str__(self):
+    return repr(self)
+
+
 class AvailabilityFinder(object):
   '''Generates availability information for APIs by looking at API schemas and
   _features files over multiple release versions of Chrome.
   '''
 
   def __init__(self,
                branch_utility,
                compiled_fs_factory,
                file_system_iterator,
                host_file_system,
@@ skipping 11 matching lines @@
 
   def _GetPredeterminedAvailability(self, api_name):
     '''Checks a configuration file for hardcoded (i.e. predetermined)
     availability information for an API.
     '''
     api_info = self._json_fs.GetFromFile(
         JSON_TEMPLATES + 'api_availabilities.json').Get().get(api_name)
     if api_info is None:
       return None
     if api_info['channel'] == 'stable':
-      return self._branch_utility.GetStableChannelInfo(api_info['version'])
-    else:
-      return self._branch_utility.GetChannelInfo(api_info['channel'])
+      return AvailabilityInfo(
+          self._branch_utility.GetStableChannelInfo(api_info['version']))
+    return AvailabilityInfo(
+        self._branch_utility.GetChannelInfo(api_info['channel']))
 
   def _GetApiSchemaFilename(self, api_name, file_system, version):
     '''Gets the name of the file which may contain the schema for |api_name| in
     |file_system|, or None if the API is not found. Note that this may be the
     single _EXTENSION_API file which all APIs share in older versions of Chrome,
     in which case it is unknown whether the API actually exists there.
     '''
     if version == 'trunk' or version > _ORIGINAL_FEATURES_MIN_VERSION:
       # API schema filenames switch format to unix_hacker_style.
       api_name = UnixName(api_name)
@@ skipping 118 matching lines @@
     determined to be 'stable' at the given version.
     '''
     if channel_info.channel == 'stable':
       return self._CheckStableAvailability(api_name,
                                            file_system,
                                            channel_info.version)
     return self._CheckChannelAvailability(api_name,
                                           file_system,
                                           channel_info)
 
+  def _FindScheduled(self, api_name):
+    '''Determines the earliest version of Chrome where the API is stable.
+    Unlike the code in GetApiAvailability, this checks if the API is stable
+    even when Chrome is in dev or beta, which shows that the API is scheduled
+    to be stable in that verison of Chrome.
+    '''
+    def check_scheduled(file_system, channel_info):
+      return self._CheckStableAvailability(
+          api_name, file_system, channel_info.version)
+
+    stable_channel = self._file_system_iterator.Descending(
+        self._branch_utility.GetChannelInfo('dev'), check_scheduled)
+
+    return stable_channel.version if stable_channel else None
+
   def GetApiAvailability(self, api_name):
     '''Performs a search for an API's top-level availability by using a
     HostFileSystemIterator instance to traverse multiple version of the
     SVN filesystem.
     '''
     availability = self._top_level_object_store.Get(api_name).Get()
     if availability is not None:
       return availability
 
     # Check for predetermined availability and cache this information if found.
     availability = self._GetPredeterminedAvailability(api_name)
     if availability is not None:
       self._top_level_object_store.Set(api_name, availability)
       return availability
 
     def check_api_availability(file_system, channel_info):
       return self._CheckApiAvailability(api_name, file_system, channel_info)
 
-    availability = self._file_system_iterator.Descending(
+    channel_info = self._file_system_iterator.Descending(
         self._branch_utility.GetChannelInfo('dev'),
         check_api_availability)
-    if availability is None:
+    if channel_info is None:
       # The API wasn't available on 'dev', so it must be a 'trunk'-only API.
-      availability = self._branch_utility.GetChannelInfo('trunk')
+      channel_info = self._branch_utility.GetChannelInfo('trunk')
+
+    # If the API is not stable, check when it will be scheduled to be stable.
+    if channel_info.channel == 'stable':
+      scheduled = None
+    else:
+      scheduled = self._FindScheduled(api_name)
+
+    availability = AvailabilityInfo(channel_info, scheduled=scheduled)
+
     self._top_level_object_store.Set(api_name, availability)
     return availability
 
   def GetApiNodeAvailability(self, api_name):
     '''Returns an APISchemaGraph annotated with each node's availability (the
     ChannelInfo at the oldest channel it's available in).
     '''
     availability_graph = self._node_level_object_store.Get(api_name).Get()
     if availability_graph is not None:
       return availability_graph
@@ skipping 32 matching lines @@
         availability_graph.Update(version_graph.Subtract(availability_graph),
                                   annotation=channel_info)
 
       previous.stat = version_stat
       previous.graph = version_graph
 
       # Continue looping until there are no longer differences between this
       # version and trunk.
       return version_stat != trunk_stat
 
-    self._file_system_iterator.Ascending(self.GetApiAvailability(api_name),
-                                         update_availability_graph)
+    self._file_system_iterator.Ascending(
+        self.GetApiAvailability(api_name).channel_info,
+        update_availability_graph)
 
     self._node_level_object_store.Set(api_name, availability_graph)
     return availability_graph