def __init__(self, content_script_apis, jsc_model, availability_finder,
json_cache, template_cache, features_bundle,
event_byname_future, platform):
self._content_script_apis = content_script_apis
self._availability = availability_finder.GetAPIAvailability(
jsc_model.name)
self._current_node = APINodeCursor(availability_finder, jsc_model.name)
self._api_availabilities = json_cache.GetFromFile(
posixpath.join(JSON_TEMPLATES, 'api_availabilities.json'))
self._intro_tables = json_cache.GetFromFile(
posixpath.join(JSON_TEMPLATES, 'intro_tables.json'))
self._api_features = features_bundle.GetAPIFeatures()
self._template_cache = template_cache
self._event_byname_future = event_byname_future
self._jsc_model = jsc_model
self._platform = platform
class _JSCViewBuilder(object):
'''Uses a Model from the JSON Schema Compiler and generates a dict that
a Motemplate template can use for a data source.
'''
def __init__(self, content_script_apis, jsc_model, availability_finder,
json_cache, template_cache, features_bundle,
event_byname_future, platform, samples):
self._content_script_apis = content_script_apis
self._availability = availability_finder.GetAPIAvailability(
jsc_model.name)
self._current_node = APINodeCursor(availability_finder, jsc_model.name)
self._api_availabilities = json_cache.GetFromFile(
posixpath.join(JSON_TEMPLATES, 'api_availabilities.json'))
self._intro_tables = json_cache.GetFromFile(
posixpath.join(JSON_TEMPLATES, 'intro_tables.json'))
self._api_features = features_bundle.GetAPIFeatures()
self._template_cache = template_cache
self._event_byname_future = event_byname_future
self._jsc_model = jsc_model
self._platform = platform
self._samples = samples
def _GetLink(self, link):
ref = link if '.' in link else (self._jsc_model.name + '.' + link)
return {'ref': ref, 'text': link, 'name': link}
def ToDict(self, request):
'''Returns a dictionary representation of |self._jsc_model|, which
is a Namespace object from JSON Schema Compiler.
'''
assert self._jsc_model is not None
chrome_dot_name = 'chrome.%s' % self._jsc_model.name
as_dict = {
'channelWarning':
self._GetChannelWarning(),
'documentationOptions':
self._jsc_model.documentation_options,
'domEvents':
self._GenerateDomEvents(self._jsc_model.events),
'events':
self._GenerateEvents(self._jsc_model.events),
'functions':
self._GenerateFunctions(self._jsc_model.functions),
'introList':
self._GetIntroTableList(),
'name':
self._jsc_model.name,
'namespace':
self._jsc_model.documentation_options.get('namespace',
chrome_dot_name),
'properties':
self._GenerateProperties(self._jsc_model.properties),
'samples':
CreateSamplesView(self._samples, request),
'title':
self._jsc_model.documentation_options.get('title',
chrome_dot_name),
'types':
self._GenerateTypes(self._jsc_model.types.values()),
}
if self._jsc_model.deprecated:
as_dict['deprecated'] = self._jsc_model.deprecated
as_dict['byName'] = _GetByNameDict(as_dict)
return as_dict
def _IsExperimental(self):
return self._jsc_model.name.startswith('experimental')
def _GetChannelWarning(self):
if not self._IsExperimental():
return {self._availability.channel_info.channel: True}
return None
def _GenerateCallback(self, callback):
'''Returns a dictionary representation of a callback suitable
for consumption by templates.
'''
if not callback:
return None
callback_dict = {
'name': callback.simple_name,
'simple_type': {
'simple_type': 'function'
},
'optional': callback.optional,
'parameters': []
}
with self._current_node.Descend('parameters', callback.simple_name,
'parameters'):
for param in callback.params:
callback_dict['parameters'].append(
self._GenerateProperty(param))
if (len(callback_dict['parameters']) > 0):
callback_dict['parameters'][-1]['last'] = True
return callback_dict
def _GenerateCallbackProperty(self, callback, callback_dict):
'''Returns a dictionary representation of a callback property
suitable for consumption by templates.
'''
property_dict = {
'name': callback.simple_name,
'description': callback.description,
'optional': callback.optional,
'isCallback': True,
'asFunction': callback_dict,
'id': _CreateId(callback, 'property'),
'simple_type': 'function',
}
if (callback.parent is not None
and not isinstance(callback.parent, model.Namespace)):
property_dict['parentName'] = callback.parent.simple_name
return property_dict
def _GenerateTypes(self, types):
'''Returns a list of dictionaries representing this Model's types.
'''
with self._current_node.Descend('types'):
return [self._GenerateType(t) for t in types]
def _GenerateType(self, type_):
'''Returns a dictionary representation of a type from JSON Schema Compiler.
'''
with self._current_node.Descend(type_.simple_name):
type_dict = {
'name':
type_.simple_name,
'description':
type_.description,
'properties':
self._GenerateProperties(type_.properties),
'functions':
self._GenerateFunctions(type_.functions),
'events':
self._GenerateEvents(type_.events),
'id':
_CreateId(type_, 'type'),
'availability':
self._GetAvailabilityTemplate(
is_enum=type_.property_type == model.PropertyType.ENUM)
}
self._RenderTypeInformation(type_, type_dict)
return type_dict
def _GenerateFunctions(self, functions):
'''Returns a list of dictionaries representing this Model's functions.
'''
with self._current_node.Descend('functions'):
return [self._GenerateFunction(f) for f in functions.values()]
def _GenerateFunction(self, function):
'''Returns a dictionary representation of a function from
JSON Schema Compiler.
'''
# When ignoring types, properties must be ignored as well.
with self._current_node.Descend(function.simple_name,
ignore=('types', 'properties')):
function_dict = {
'name': function.simple_name,
'description': function.description,
'callback': self._GenerateCallback(function.callback),
'parameters': [],
'returns': None,
'id': _CreateId(function, 'method'),
'availability': self._GetAvailabilityTemplate()
}
self._AddCommonProperties(function_dict, function)
if function.returns:
function_dict['returns'] = self._GenerateType(function.returns)
with self._current_node.Descend(function.simple_name, 'parameters'):
for param in function.params:
function_dict['parameters'].append(
self._GenerateProperty(param))
if function.callback is not None:
# Show the callback as an extra parameter.
function_dict['parameters'].append(
self._GenerateCallbackProperty(function.callback,
function_dict['callback']))
if len(function_dict['parameters']) > 0:
function_dict['parameters'][-1]['last'] = True
return function_dict
def _GenerateEvents(self, events):
'''Returns a list of dictionaries representing this Model's events.
'''
with self._current_node.Descend('events'):
return [
self._GenerateEvent(e) for e in events.values()
if not e.supports_dom
]
def _GenerateDomEvents(self, events):
'''Returns a list of dictionaries representing this Model's DOM events.
'''
with self._current_node.Descend('events'):
return [
self._GenerateEvent(e) for e in events.values()
if e.supports_dom
]
def _GenerateEvent(self, event):
'''Returns a dictionary representation of an event from
JSON Schema Compiler. Note that although events are modeled as functions
in JSON Schema Compiler, we model them differently for the templates.
'''
with self._current_node.Descend(event.simple_name,
ignore=('properties', )):
event_dict = {
'name':
event.simple_name,
'description':
event.description,
'filters': [self._GenerateProperty(f) for f in event.filters],
'conditions':
[self._GetLink(condition) for condition in event.conditions],
'actions': [self._GetLink(action) for action in event.actions],
'supportsRules':
event.supports_rules,
'supportsListeners':
event.supports_listeners,
'properties': [],
'id':
_CreateId(event, 'event'),
'byName': {},
'availability':
self._GetAvailabilityTemplate()
}
self._AddCommonProperties(event_dict, event)
# Add the Event members to each event in this object.
if self._event_byname_future:
event_dict['byName'].update(self._event_byname_future.Get())
# We need to create the method description for addListener based on the
# information stored in |event|.
if event.supports_listeners:
callback_object = model.Function(parent=event,
name='callback',
json={},
namespace=event.parent,
origin='')
callback_object.params = event.params
if event.callback:
callback_object.callback = event.callback
with self._current_node.Descend(event.simple_name):
callback = self._GenerateFunction(callback_object)
callback_parameter = self._GenerateCallbackProperty(
callback_object, callback)
callback_parameter['last'] = True
event_dict['byName']['addListener'] = {
'name': 'addListener',
'callback': callback,
'parameters': [callback_parameter]
}
if event.supports_dom:
# Treat params as properties of the custom Event object associated with
# this DOM Event.
with self._current_node.Descend(event.simple_name,
ignore=('properties', )):
event_dict['properties'] += [
self._GenerateProperty(param) for param in event.params
]
return event_dict
def _GenerateProperties(self, properties):
'''Returns a list of dictionaries representing this Model's properites.
'''
with self._current_node.Descend('properties'):
return [self._GenerateProperty(v) for v in properties.values()]
def _GenerateProperty(self, property_):
'''Returns a dictionary representation of a property from
JSON Schema Compiler.
'''
if not hasattr(property_, 'type_'):
for d in dir(property_):
if not d.startswith('_'):
print('%s -> %s' % (d, getattr(property_, d)))
type_ = property_.type_
# Make sure we generate property info for arrays, too.
# TODO(kalman): what about choices?
if type_.property_type == model.PropertyType.ARRAY:
properties = type_.item_type.properties
else:
properties = type_.properties
with self._current_node.Descend(property_.simple_name):
property_dict = {
'name': property_.simple_name,
'optional': property_.optional,
'description': property_.description,
'properties': self._GenerateProperties(type_.properties),
'functions': self._GenerateFunctions(type_.functions),
'parameters': [],
'returns': None,
'id': _CreateId(property_, 'property'),
'availability': self._GetAvailabilityTemplate()
}
self._AddCommonProperties(property_dict, property_)
if type_.property_type == model.PropertyType.FUNCTION:
function = type_.function
with self._current_node.Descend('parameters'):
for param in function.params:
property_dict['parameters'].append(
self._GenerateProperty(param))
if function.returns:
with self._current_node.Descend(ignore=('types',
'properties')):
property_dict['returns'] = self._GenerateType(
function.returns)
value = property_.value
if value is not None:
if isinstance(value, int):
property_dict['value'] = _FormatValue(value)
else:
property_dict['value'] = value
else:
self._RenderTypeInformation(type_, property_dict)
return property_dict
def _AddCommonProperties(self, target, src):
if src.deprecated is not None:
target['deprecated'] = src.deprecated
if (src.parent is not None
and not isinstance(src.parent, model.Namespace)):
target['parentName'] = src.parent.simple_name
def _RenderTypeInformation(self, type_, dst_dict):
with self._current_node.Descend(ignore=('types', 'properties')):
dst_dict[
'is_object'] = type_.property_type == model.PropertyType.OBJECT
if type_.property_type == model.PropertyType.CHOICES:
dst_dict['choices'] = self._GenerateTypes(type_.choices)
# We keep track of which == last for knowing when to add "or" between
# choices in templates.
if len(dst_dict['choices']) > 0:
dst_dict['choices'][-1]['last'] = True
elif type_.property_type == model.PropertyType.REF:
dst_dict['link'] = self._GetLink(type_.ref_type)
elif type_.property_type == model.PropertyType.ARRAY:
dst_dict['array'] = self._GenerateType(type_.item_type)
elif type_.property_type == model.PropertyType.ENUM:
dst_dict['enum_values'] = [{
'name': value.name,
'description': value.description
} for value in type_.enum_values]
if len(dst_dict['enum_values']) > 0:
dst_dict['enum_values'][-1]['last'] = True
elif type_.instance_of is not None:
dst_dict['simple_type'] = type_.instance_of
else:
dst_dict['simple_type'] = type_.property_type.name
def _CreateAvailabilityTemplate(self, status, scheduled, version):
'''Returns an object suitable for use in templates to display availability
information.
'''
return {
'partial':
self._template_cache.GetFromFile(
'%sintro_tables/%s_message.html' %
(PRIVATE_TEMPLATES, status)).Get(),
'scheduled':
scheduled,
'version':
version
}
def _GetAvailabilityTemplate(self, is_enum=False):
'''Gets availability for the current node and returns an appropriate
template object.
'''
# We don't show an availability warning for enums.
# TODO(devlin): We should also render enums differently, indicating that
# symbolic constants are available from version 44 onwards.
if is_enum:
return None
# Displaying deprecated status takes precedence over when the API
# became stable.
availability_info = self._current_node.GetDeprecated()
if availability_info is not None:
status = 'deprecated'
else:
availability_info = self._current_node.GetAvailability()
if availability_info is None:
return None
status = availability_info.channel_info.channel
return self._CreateAvailabilityTemplate(
status, availability_info.scheduled,
availability_info.channel_info.version)
def _GetIntroTableList(self):
'''Create a generic data structure that can be traversed by the templates
to create an API intro table.
'''
intro_rows = [
self._GetIntroDescriptionRow(),
self._GetIntroAvailabilityRow()
] + self._GetIntroDependencyRows() + self._GetIntroContentScriptRow()
# Add rows using data from intro_tables.json, overriding any existing rows
# if they share the same 'title' attribute.
row_titles = [row['title'] for row in intro_rows]
for misc_row in self._GetMiscIntroRows():
if misc_row['title'] in row_titles:
intro_rows[row_titles.index(misc_row['title'])] = misc_row
else:
intro_rows.append(misc_row)
return intro_rows
def _GetIntroContentScriptRow(self):
'''Generates the 'Content Script' row data for an API intro table.
'''
content_script_support = self._content_script_apis.get(
self._jsc_model.name)
if content_script_support is None:
return []
if content_script_support.restrictedTo:
content_script_support.restrictedTo.sort(key=itemgetter('node'))
MarkFirstAndLast(content_script_support.restrictedTo)
return [{
'title':
'Content Scripts',
'content': [{
'partial':
self._template_cache.GetFromFile(
posixpath.join(PRIVATE_TEMPLATES, 'intro_tables',
'content_scripts.html')).Get(),
'contentScriptSupport':
content_script_support.__dict__
}]
}]
def _GetIntroDescriptionRow(self):
''' Generates the 'Description' row data for an API intro table.
'''
return {
'title': 'Description',
'content': [{
'text': self._jsc_model.description
}]
}
def _GetIntroAvailabilityRow(self):
''' Generates the 'Availability' row data for an API intro table.
'''
if self._IsExperimental():
status = 'experimental'
scheduled = None
version = None
else:
status = self._availability.channel_info.channel
scheduled = self._availability.scheduled
version = self._availability.channel_info.version
return {
'title':
'Availability',
'content':
[self._CreateAvailabilityTemplate(status, scheduled, version)]
}
def _GetIntroDependencyRows(self):
# Devtools aren't in _api_features. If we're dealing with devtools, bail.
if 'devtools' in self._jsc_model.name:
return []
api_feature = self._api_features.Get().get(self._jsc_model.name)
if not api_feature:
logging.error('"%s" not found in _api_features.json' %
self._jsc_model.name)
return []
permissions_content = []
manifest_content = []
def categorize_dependency(dependency):
def make_code_node(text):
return {'class': 'code', 'text': text}
context, name = dependency.split(':', 1)
if context == 'permission':
permissions_content.append(make_code_node('"%s"' % name))
elif context == 'manifest':
manifest_content.append(make_code_node('"%s": {...}' % name))
elif context == 'api':
transitive_dependencies = (self._api_features.Get().get(
name, {}).get('dependencies', []))
for transitive_dependency in transitive_dependencies:
categorize_dependency(transitive_dependency)
else:
logging.error('Unrecognized dependency for %s: %s' %
(self._jsc_model.name, context))
for dependency in api_feature.get('dependencies', ()):
categorize_dependency(dependency)
dependency_rows = []
if permissions_content:
dependency_rows.append({
'title': 'Permissions',
'content': permissions_content
})
if manifest_content:
dependency_rows.append({
'title': 'Manifest',
'content': manifest_content
})
return dependency_rows
def _GetMiscIntroRows(self):
''' Generates miscellaneous intro table row data, such as 'Permissions',
'Samples', and 'Learn More', using intro_tables.json.
'''
misc_rows = []
# 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().get(self._jsc_model.name)
if table_info is None:
return misc_rows
for category in table_info.iterkeys():
content = []
for node in table_info[category]:
ext_type = PlatformToExtensionType(self._platform)
# Don't display nodes restricted to a different platform.
if ext_type not in node.get('extension_types', (ext_type, )):
continue
# If there is a 'partial' argument and it hasn't already been
# converted to a Motemplate object, transform it to a template.
if 'partial' in node:
# Note: it's enough to copy() not deepcopy() because only a single
# top-level key is being modified.
node = copy(node)
node['partial'] = self._template_cache.GetFromFile(
posixpath.join(PRIVATE_TEMPLATES,
node['partial'])).Get()
content.append(node)
misc_rows.append({'title': category, 'content': content})
return misc_rows