chrome/common/extensions/docs/server2/reference_resolver.py

   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
   5 from copy import copy
   6 import logging
   7 import re
   8
   9 from file_system import FileNotFoundError
  10 from third_party.json_schema_compiler.model import PropertyType
  11
  12
  13 def _ClassifySchemaNode(node_name, node):
  14   """Attempt to classify |node_name| in an API, determining whether |node_name|
  15   refers to a type, function, event, or property in |api|.
  16   """
  17   if '.' in node_name:
  18     node_name, rest = node_name.split('.', 1)
  19   else:
  20     rest = None
  21   for key, group in [('types', 'type'),
  22                      ('functions', 'method'),
  23                      ('events', 'event'),
  24                      ('properties', 'property')]:
  25     for item in getattr(node, key, {}).itervalues():
  26       if item.simple_name == node_name:
  27         if rest is not None:
  28           ret = _ClassifySchemaNode(rest, item)
  29           if ret is not None:
  30             return ret
  31         else:
  32           return group, node_name
  33   return None
  34
  35
  36 def _MakeKey(namespace, ref):
  37   key = '%s/%s' % (namespace, ref)
  38   # AppEngine doesn't like keys > 500, but there will be some other stuff
  39   # that goes into this key, so truncate it earlier.  This shoudn't be
  40   # happening anyway unless there's a bug, such as http://crbug.com/314102.
  41   max_size = 256
  42   if len(key) > max_size:
  43     logging.error('Key was >%s characters: %s' % (max_size, key))
  44     key = key[:max_size]
  45   return key
  46
  47
  48 class ReferenceResolver(object):
  49   """Resolves references to $ref's by searching through the APIs to find the
  50   correct node. See document_renderer.py for more information on $ref syntax.
  51   """
  52   def __init__(self, api_models, object_store):
  53     self._api_models = api_models
  54     self._object_store = object_store
  55
  56   def _GetRefLink(self, ref, api_list, namespace):
  57     # Check nodes within each API the ref might refer to.
  58     parts = ref.split('.')
  59     for i in xrange(1, len(parts)):
  60       api_name = '.'.join(parts[:i])
  61       if api_name not in api_list:
  62         continue
  63       try:
  64         api_model = self._api_models.GetModel(api_name).Get()
  65       except FileNotFoundError:
  66         continue
  67       name = '.'.join(parts[i:])
  68       # Attempt to find |name| in the API.
  69       node_info = _ClassifySchemaNode(name, api_model)
  70       if node_info is None:
  71         # Check to see if this ref is a property. If it is, we want the ref to
  72         # the underlying type the property is referencing.
  73         for prop in api_model.properties.itervalues():
  74           # If the name of this property is in the ref text, replace the
  75           # property with its type, and attempt to classify it.
  76           if prop.name in name and prop.type_.property_type == PropertyType.REF:
  77             name_as_prop_type = name.replace(prop.name, prop.type_.ref_type)
  78             node_info = _ClassifySchemaNode(name_as_prop_type, api_model)
  79             if node_info is not None:
  80               name = name_as_prop_type
  81               text = ref.replace(prop.name, prop.type_.ref_type)
  82               break
  83         if node_info is None:
  84           continue
  85       else:
  86         text = ref
  87       category, node_name = node_info
  88       if namespace is not None and text.startswith('%s.' % namespace):
  89         text = text[len('%s.' % namespace):]
  90       api_model = self._api_models.GetModel(api_name).Get()
  91       filename = api_model.documentation_options.get('documented_in', api_name)
  92       return {
  93         'href': '%s#%s-%s' % (filename, category, name.replace('.', '-')),
  94         'text': text,
  95         'name': node_name
  96       }
  97
  98     # If it's not a reference to an API node it might just be a reference to an
  99     # API. Check this last so that links within APIs take precedence over links
 100     # to other APIs.
 101     if ref in api_list:
 102       return {
 103         'href': '%s' % ref,
 104         'text': ref,
 105         'name': ref
 106       }
 107
 108     return None
 109
 110   def GetLink(self, ref, namespace=None, title=None):
 111     """Resolve $ref |ref| in namespace |namespace| if not None, returning None
 112     if it cannot be resolved.
 113     """
 114     db_key = _MakeKey(namespace, ref)
 115     link = self._object_store.Get(db_key).Get()
 116     if link is None:
 117       api_list = self._api_models.GetNames()
 118       link = self._GetRefLink(ref, api_list, namespace)
 119       if link is None and namespace is not None:
 120         # Try to resolve the ref in the current namespace if there is one.
 121         link = self._GetRefLink('%s.%s' % (namespace, ref), api_list, namespace)
 122       if link is None:
 123         return None
 124       self._object_store.Set(db_key, link)
 125
 126     if title is not None:
 127       link = copy(link)
 128       link['text'] = title
 129
 130     return link
 131
 132   def SafeGetLink(self, ref, namespace=None, title=None):
 133     """Resolve $ref |ref| in namespace |namespace|, or globally if None. If it
 134     cannot be resolved, pretend like it is a link to a type.
 135     """
 136     ref_data = self.GetLink(ref, namespace=namespace, title=title)
 137     if ref_data is not None:
 138       return ref_data
 139     logging.error('$ref %s could not be resolved in namespace %s.' %
 140         (ref, namespace))
 141     type_name = ref.rsplit('.', 1)[-1]
 142     return {
 143       'href': '#type-%s' % type_name,
 144       'text': title or ref,
 145       'name': ref
 146     }