googleapiclient.schema

Package googleapiclient :: Module schema |
[hide private]
[frames] | no frames]

# Source Code for Module googleapiclient.schema

      1  # Copyright 2014 Google Inc. All Rights Reserved.
      2  #
      3  # Licensed under the Apache License, Version 2.0 (the "License");
      4  # you may not use this file except in compliance with the License.
      5  # You may obtain a copy of the License at
      6  #
      7  #      http://www.apache.org/licenses/LICENSE-2.0
      8  #
      9  # Unless required by applicable law or agreed to in writing, software
     10  # distributed under the License is distributed on an "AS IS" BASIS,
     11  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     12  # See the License for the specific language governing permissions and
     13  # limitations under the License.
     14
     15  """Schema processing for discovery based APIs
     16
     17  Schemas holds an APIs discovery schemas. It can return those schema as
     18  deserialized JSON objects, or pretty print them as prototype objects that
     19  conform to the schema.
     20
     21  For example, given the schema:
     22
     23   schema = \"\"\"{
     24     "Foo": {
     25      "type": "object",
     26      "properties": {
     27       "etag": {
     28        "type": "string",
     29        "description": "ETag of the collection."
     30       },
     31       "kind": {
     32        "type": "string",
     33        "description": "Type of the collection ('calendar#acl').",
     34        "default": "calendar#acl"
     35       },
     36       "nextPageToken": {
     37        "type": "string",
     38        "description": "Token used to access the next
     39           page of this result. Omitted if no further results are available."
     40       }
     41      }
     42     }
     43   }\"\"\"
     44
     45   s = Schemas(schema)
     46   print s.prettyPrintByName('Foo')
     47
     48   Produces the following output:
     49
     50    {
     51     "nextPageToken": "A String", # Token used to access the
     52         # next page of this result. Omitted if no further results are available.
     53     "kind": "A String", # Type of the collection ('calendar#acl').
     54     "etag": "A String", # ETag of the collection.
     55    },
     56
     57  The constructor takes a discovery document in which to look up named schema.
     58  """
     59  from __future__ import absolute_import
     60  import six
     61
     62  # TODO(jcgregorio) support format, enum, minimum, maximum
     63
     64  __author__ = "jcgregorio@google.com (Joe Gregorio)"
     65
     66  import copy
     67
     68  from googleapiclient import _helpers as util
     69
     70
     71 -class Schemas(object):
     72      """Schemas for an API."""
     73
     74 -    def __init__(self, discovery):
     75          """Constructor.
     76
     77      Args:
     78        discovery: object, Deserialized discovery document from which we pull
     79          out the named schema.
     80      """
     81          self.schemas = discovery.get("schemas", {})
     82
     83          # Cache of pretty printed schemas.
     84          self.pretty = {}
     85
     86      @util.positional(2)
     87 -    def _prettyPrintByName(self, name, seen=None, dent=0):
     88          """Get pretty printed object prototype from the schema name.
     89
     90      Args:
     91        name: string, Name of schema in the discovery document.
     92        seen: list of string, Names of schema already seen. Used to handle
     93          recursive definitions.
     94
     95      Returns:
     96        string, A string that contains a prototype object with
     97          comments that conforms to the given schema.
     98      """
     99          if seen is None:
    100              seen = []
    101
    102          if name in seen:
    103              # Do not fall into an infinite loop over recursive definitions.
    104              return "# Object with schema name: %s" % name
    105          seen.append(name)
    106
    107          if name not in self.pretty:
    108              self.pretty[name] = _SchemaToStruct(
    109                  self.schemas[name], seen, dent=dent
    110              ).to_str(self._prettyPrintByName)
    111
    112          seen.pop()
    113
    114          return self.pretty[name]
    115
    116 -    def prettyPrintByName(self, name):
    117          """Get pretty printed object prototype from the schema name.
    118
    119      Args:
    120        name: string, Name of schema in the discovery document.
    121
    122      Returns:
    123        string, A string that contains a prototype object with
    124          comments that conforms to the given schema.
    125      """
    126          # Return with trailing comma and newline removed.
    127          return self._prettyPrintByName(name, seen=[], dent=1)[:-2]
    128
    129      @util.positional(2)
    130 -    def _prettyPrintSchema(self, schema, seen=None, dent=0):
    131          """Get pretty printed object prototype of schema.
    132
    133      Args:
    134        schema: object, Parsed JSON schema.
    135        seen: list of string, Names of schema already seen. Used to handle
    136          recursive definitions.
    137
    138      Returns:
    139        string, A string that contains a prototype object with
    140          comments that conforms to the given schema.
    141      """
    142          if seen is None:
    143              seen = []
    144
    145          return _SchemaToStruct(schema, seen, dent=dent).to_str(self._prettyPrintByName)
    146
    147 -    def prettyPrintSchema(self, schema):
    148          """Get pretty printed object prototype of schema.
    149
    150      Args:
    151        schema: object, Parsed JSON schema.
    152
    153      Returns:
    154        string, A string that contains a prototype object with
    155          comments that conforms to the given schema.
    156      """
    157          # Return with trailing comma and newline removed.
    158          return self._prettyPrintSchema(schema, dent=1)[:-2]
    159
    160 -    def get(self, name, default=None):
    161          """Get deserialized JSON schema from the schema name.
    162
    163      Args:
    164        name: string, Schema name.
    165        default: object, return value if name not found.
    166      """
    167          return self.schemas.get(name, default)
    168
    169
    170 -class _SchemaToStruct(object):
    171      """Convert schema to a prototype object."""
    172
    173      @util.positional(3)
    174 -    def __init__(self, schema, seen, dent=0):
    175          """Constructor.
    176
    177      Args:
    178        schema: object, Parsed JSON schema.
    179        seen: list, List of names of schema already seen while parsing. Used to
    180          handle recursive definitions.
    181        dent: int, Initial indentation depth.
    182      """
    183          # The result of this parsing kept as list of strings.
    184          self.value = []
    185
    186          # The final value of the parsing.
    187          self.string = None
    188
    189          # The parsed JSON schema.
    190          self.schema = schema
    191
    192          # Indentation level.
    193          self.dent = dent
    194
    195          # Method that when called returns a prototype object for the schema with
    196          # the given name.
    197          self.from_cache = None
    198
    199          # List of names of schema already seen while parsing.
    200          self.seen = seen
    201
    202 -    def emit(self, text):
    203          """Add text as a line to the output.
    204
    205      Args:
    206        text: string, Text to output.
    207      """
    208          self.value.extend(["  " * self.dent, text, "\n"])
    209
    210 -    def emitBegin(self, text):
    211          """Add text to the output, but with no line terminator.
    212
    213      Args:
    214        text: string, Text to output.
    215        """
    216          self.value.extend(["  " * self.dent, text])
    217
    218 -    def emitEnd(self, text, comment):
    219          """Add text and comment to the output with line terminator.
    220
    221      Args:
    222        text: string, Text to output.
    223        comment: string, Python comment.
    224      """
    225          if comment:
    226              divider = "\n" + "  " * (self.dent + 2) + "# "
    227              lines = comment.splitlines()
    228              lines = [x.rstrip() for x in lines]
    229              comment = divider.join(lines)
    230              self.value.extend([text, " # ", comment, "\n"])
    231          else:
    232              self.value.extend([text, "\n"])
    233
    234 -    def indent(self):
    235          """Increase indentation level."""
    236          self.dent += 1
    237
    238 -    def undent(self):
    239          """Decrease indentation level."""
    240          self.dent -= 1
    241
    242 -    def _to_str_impl(self, schema):
    243          """Prototype object based on the schema, in Python code with comments.
    244
    245      Args:
    246        schema: object, Parsed JSON schema file.
    247
    248      Returns:
    249        Prototype object based on the schema, in Python code with comments.
    250      """
    251          stype = schema.get("type")
    252          if stype == "object":
    253              self.emitEnd("{", schema.get("description", ""))
    254              self.indent()
    255              if "properties" in schema:
    256                  for pname, pschema in six.iteritems(schema.get("properties", {})):
    257                      self.emitBegin('"%s": ' % pname)
    258                      self._to_str_impl(pschema)
    259              elif "additionalProperties" in schema:
    260                  self.emitBegin('"a_key": ')
    261                  self._to_str_impl(schema["additionalProperties"])
    262              self.undent()
    263              self.emit("},")
    264          elif "$ref" in schema:
    265              schemaName = schema["$ref"]
    266              description = schema.get("description", "")
    267              s = self.from_cache(schemaName, seen=self.seen)
    268              parts = s.splitlines()
    269              self.emitEnd(parts[0], description)
    270              for line in parts[1:]:
    271                  self.emit(line.rstrip())
    272          elif stype == "boolean":
    273              value = schema.get("default", "True or False")
    274              self.emitEnd("%s," % str(value), schema.get("description", ""))
    275          elif stype == "string":
    276              value = schema.get("default", "A String")
    277              self.emitEnd('"%s",' % str(value), schema.get("description", ""))
    278          elif stype == "integer":
    279              value = schema.get("default", "42")
    280              self.emitEnd("%s," % str(value), schema.get("description", ""))
    281          elif stype == "number":
    282              value = schema.get("default", "3.14")
    283              self.emitEnd("%s," % str(value), schema.get("description", ""))
    284          elif stype == "null":
    285              self.emitEnd("None,", schema.get("description", ""))
    286          elif stype == "any":
    287              self.emitEnd('"",', schema.get("description", ""))
    288          elif stype == "array":
    289              self.emitEnd("[", schema.get("description"))
    290              self.indent()
    291              self.emitBegin("")
    292              self._to_str_impl(schema["items"])
    293              self.undent()
    294              self.emit("],")
    295          else:
    296              self.emit("Unknown type! %s" % stype)
    297              self.emitEnd("", "")
    298
    299          self.string = "".join(self.value)
    300          return self.string
    301
    302 -    def to_str(self, from_cache):
    303          """Prototype object based on the schema, in Python code with comments.
    304
    305      Args:
    306        from_cache: callable(name, seen), Callable that retrieves an object
    307           prototype for a schema with the given name. Seen is a list of schema
    308           names already seen as we recursively descend the schema definition.
    309
    310      Returns:
    311        Prototype object based on the schema, in Python code with comments.
    312        The lines of the code will all be properly indented.
    313      """
    314          self.from_cache = from_cache
    315          return self._to_str_impl(self.schema)
    316