api_list_data_source.py revision 6d86b77056ed63eb6871182f42a9fd5f07550f90 
1# Copyright (c) 2012 The Chromium Authors. All rights reserved.
2# Use of this source code is governed by a BSD-style license that can be
3# found in the LICENSE file.
4
5from data_source import DataSource
6from future import Future
7from operator import itemgetter
8
9from docs_server_utils import MarkLast, StringIdentity
10
11class APIListDataSource(DataSource):
12  """ This class creates a list of chrome.* APIs and chrome.experimental.* APIs
13  for extensions and apps that are used in the api_index.html,
14  experimental.html, and private_apis.html pages.
15
16  An API is considered listable if it is listed in _api_features.json,
17  it has a corresponding HTML file in the public template path, and one of
18  the following conditions is met:
19    - It has no "dependencies" or "extension_types" properties in _api_features
20    - It has an "extension_types" property in _api_features with either/both
21      "extension"/"platform_app" values present.
22    - It has a dependency in _{api,manifest,permission}_features with an
23      "extension_types" property where either/both "extension"/"platform_app"
24      values are present.
25  """
26  def __init__(self, server_instance, _):
27    self._features_bundle = server_instance.features_bundle
28    self._api_models = server_instance.api_models
29    self._object_store = server_instance.object_store_creator.Create(
30        # Update the model when the API or Features model updates.
31        APIListDataSource,
32        category=StringIdentity(self._features_bundle.GetIdentity(),
33                                self._api_models.GetIdentity()))
34    self._api_categorizer = server_instance.api_categorizer
35    self._availability_finder = server_instance.availability_finder
36
37  def _GenerateAPIDict(self):
38    def get_channel_info(api_name):
39      return self._availability_finder.GetAPIAvailability(api_name).channel_info
40
41    def get_api_platform(api_name):
42      feature = self._features_bundle.GetAPIFeatures().Get()[api_name]
43      return feature['platforms']
44
45    def make_dict_for_platform(platform):
46      platform_dict = {
47        'chrome': {'stable': [], 'beta': [], 'dev': [], 'trunk': []},
48      }
49      private_apis = []
50      experimental_apis = []
51      all_apis = []
52      for api_name, api_model in self._api_models.IterModels():
53        if not self._api_categorizer.IsDocumented(platform, api_name):
54          continue
55        api = {
56          'name': api_name,
57          'description': api_model.description,
58          'platforms': get_api_platform(api_name),
59        }
60        category = self._api_categorizer.GetCategory(platform, api_name)
61        if category == 'chrome':
62          channel_info = get_channel_info(api_name)
63          channel = channel_info.channel
64          if channel == 'stable':
65            version = channel_info.version
66            api['version'] = version
67          platform_dict[category][channel].append(api)
68          all_apis.append(api)
69        elif category == 'experimental':
70          experimental_apis.append(api)
71          all_apis.append(api)
72        elif category == 'private':
73          private_apis.append(api)
74
75      for channel, apis_by_channel in platform_dict['chrome'].iteritems():
76        apis_by_channel.sort(key=itemgetter('name'))
77        MarkLast(apis_by_channel)
78        platform_dict['chrome'][channel] = apis_by_channel
79
80      for key, apis in (('all', all_apis),
81                        ('private', private_apis),
82                        ('experimental', experimental_apis)):
83        apis.sort(key=itemgetter('name'))
84        MarkLast(apis)
85        platform_dict[key] = apis
86
87      return platform_dict
88    return {
89      'apps': make_dict_for_platform('apps'),
90      'extensions': make_dict_for_platform('extensions'),
91    }
92
93  def _GetCachedAPIData(self):
94    data_future = self._object_store.Get('api_data')
95    def resolve():
96      data = data_future.Get()
97      if data is None:
98        data = self._GenerateAPIDict()
99        self._object_store.Set('api_data', data)
100      return data
101    return Future(callback=resolve)
102
103  def get(self, key):
104    return self._GetCachedAPIData().Get().get(key)
105
106  def Cron(self):
107    return self._GetCachedAPIData()
108