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  # Oauth2client < 3 has the positional helper in 'util', >= 3 has it 
 69  # in '_helpers'. 
 70  try: 
 71    from oauth2client import util 
 72  except ImportError: 
 73    from oauth2client import _helpers as util 
 74   
 75   
 76 -class Schemas(object): 
 77    """Schemas for an API.""" 
 78   
 79 -  def __init__(self, discovery): 
 80      """Constructor. 
 81   
 82      Args: 
 83        discovery: object, Deserialized discovery document from which we pull 
 84          out the named schema. 
 85      """ 
 86      self.schemas = discovery.get('schemas', {}) 
 87   
 88      # Cache of pretty printed schemas. 
 89      self.pretty = {} 
 90   
 91    @util.positional(2) 
 92 -  def _prettyPrintByName(self, name, seen=None, dent=0): 
 93      """Get pretty printed object prototype from the schema name. 
 94   
 95      Args: 
 96        name: string, Name of schema in the discovery document. 
 97        seen: list of string, Names of schema already seen. Used to handle 
 98          recursive definitions. 
 99   
100      Returns: 
101        string, A string that contains a prototype object with 
102          comments that conforms to the given schema. 
103      """ 
104      if seen is None: 
105        seen = [] 
106   
107      if name in seen: 
108        # Do not fall into an infinite loop over recursive definitions. 
109        return '# Object with schema name: %s' % name 
110      seen.append(name) 
111   
112      if name not in self.pretty: 
113        self.pretty[name] = _SchemaToStruct(self.schemas[name], 
114            seen, dent=dent).to_str(self._prettyPrintByName) 
115   
116      seen.pop() 
117   
118      return self.pretty[name] 
119   
120 -  def prettyPrintByName(self, name): 
121      """Get pretty printed object prototype from the schema name. 
122   
123      Args: 
124        name: string, Name of schema in the discovery document. 
125   
126      Returns: 
127        string, A string that contains a prototype object with 
128          comments that conforms to the given schema. 
129      """ 
130      # Return with trailing comma and newline removed. 
131      return self._prettyPrintByName(name, seen=[], dent=1)[:-2] 
132   
133    @util.positional(2) 
134 -  def _prettyPrintSchema(self, schema, seen=None, dent=0): 
135      """Get pretty printed object prototype of schema. 
136   
137      Args: 
138        schema: object, Parsed JSON schema. 
139        seen: list of string, Names of schema already seen. Used to handle 
140          recursive definitions. 
141   
142      Returns: 
143        string, A string that contains a prototype object with 
144          comments that conforms to the given schema. 
145      """ 
146      if seen is None: 
147        seen = [] 
148   
149      return _SchemaToStruct(schema, seen, dent=dent).to_str(self._prettyPrintByName) 
150   
151 -  def prettyPrintSchema(self, schema): 
152      """Get pretty printed object prototype of schema. 
153   
154      Args: 
155        schema: object, Parsed JSON schema. 
156   
157      Returns: 
158        string, A string that contains a prototype object with 
159          comments that conforms to the given schema. 
160      """ 
161      # Return with trailing comma and newline removed. 
162      return self._prettyPrintSchema(schema, dent=1)[:-2] 
163   
164 -  def get(self, name, default=None): 
165      """Get deserialized JSON schema from the schema name. 
166   
167      Args: 
168        name: string, Schema name. 
169        default: object, return value if name not found. 
170      """ 
171      return self.schemas.get(name, default) 
172   
173   
174 -class _SchemaToStruct(object): 
175    """Convert schema to a prototype object.""" 
176   
177    @util.positional(3) 
178 -  def __init__(self, schema, seen, dent=0): 
179      """Constructor. 
180   
181      Args: 
182        schema: object, Parsed JSON schema. 
183        seen: list, List of names of schema already seen while parsing. Used to 
184          handle recursive definitions. 
185        dent: int, Initial indentation depth. 
186      """ 
187      # The result of this parsing kept as list of strings. 
188      self.value = [] 
189   
190      # The final value of the parsing. 
191      self.string = None 
192   
193      # The parsed JSON schema. 
194      self.schema = schema 
195   
196      # Indentation level. 
197      self.dent = dent 
198   
199      # Method that when called returns a prototype object for the schema with 
200      # the given name. 
201      self.from_cache = None 
202   
203      # List of names of schema already seen while parsing. 
204      self.seen = seen 
205   
206 -  def emit(self, text): 
207      """Add text as a line to the output. 
208   
209      Args: 
210        text: string, Text to output. 
211      """ 
212      self.value.extend(["  " * self.dent, text, '\n']) 
213   
214 -  def emitBegin(self, text): 
215      """Add text to the output, but with no line terminator. 
216   
217      Args: 
218        text: string, Text to output. 
219        """ 
220      self.value.extend(["  " * self.dent, text]) 
221   
222 -  def emitEnd(self, text, comment): 
223      """Add text and comment to the output with line terminator. 
224   
225      Args: 
226        text: string, Text to output. 
227        comment: string, Python comment. 
228      """ 
229      if comment: 
230        divider = '\n' + '  ' * (self.dent + 2) + '# ' 
231        lines = comment.splitlines() 
232        lines = [x.rstrip() for x in lines] 
233        comment = divider.join(lines) 
234        self.value.extend([text, ' # ', comment, '\n']) 
235      else: 
236        self.value.extend([text, '\n']) 
237   
238 -  def indent(self): 
239      """Increase indentation level.""" 
240      self.dent += 1 
241   
242 -  def undent(self): 
243      """Decrease indentation level.""" 
244      self.dent -= 1 
245   
246 -  def _to_str_impl(self, schema): 
247      """Prototype object based on the schema, in Python code with comments. 
248   
249      Args: 
250        schema: object, Parsed JSON schema file. 
251   
252      Returns: 
253        Prototype object based on the schema, in Python code with comments. 
254      """ 
255      stype = schema.get('type') 
256      if stype == 'object': 
257        self.emitEnd('{', schema.get('description', '')) 
258        self.indent() 
259        if 'properties' in schema: 
260          for pname, pschema in six.iteritems(schema.get('properties', {})): 
261            self.emitBegin('"%s": ' % pname) 
262            self._to_str_impl(pschema) 
263        elif 'additionalProperties' in schema: 
264          self.emitBegin('"a_key": ') 
265          self._to_str_impl(schema['additionalProperties']) 
266        self.undent() 
267        self.emit('},') 
268      elif '$ref' in schema: 
269        schemaName = schema['$ref'] 
270        description = schema.get('description', '') 
271        s = self.from_cache(schemaName, seen=self.seen) 
272        parts = s.splitlines() 
273        self.emitEnd(parts[0], description) 
274        for line in parts[1:]: 
275          self.emit(line.rstrip()) 
276      elif stype == 'boolean': 
277        value = schema.get('default', 'True or False') 
278        self.emitEnd('%s,' % str(value), schema.get('description', '')) 
279      elif stype == 'string': 
280        value = schema.get('default', 'A String') 
281        self.emitEnd('"%s",' % str(value), schema.get('description', '')) 
282      elif stype == 'integer': 
283        value = schema.get('default', '42') 
284        self.emitEnd('%s,' % str(value), schema.get('description', '')) 
285      elif stype == 'number': 
286        value = schema.get('default', '3.14') 
287        self.emitEnd('%s,' % str(value), schema.get('description', '')) 
288      elif stype == 'null': 
289        self.emitEnd('None,', schema.get('description', '')) 
290      elif stype == 'any': 
291        self.emitEnd('"",', schema.get('description', '')) 
292      elif stype == 'array': 
293        self.emitEnd('[', schema.get('description')) 
294        self.indent() 
295        self.emitBegin('') 
296        self._to_str_impl(schema['items']) 
297        self.undent() 
298        self.emit('],') 
299      else: 
300        self.emit('Unknown type! %s' % stype) 
301        self.emitEnd('', '') 
302   
303      self.string = ''.join(self.value) 
304      return self.string 
305   
306 -  def to_str(self, from_cache): 
307      """Prototype object based on the schema, in Python code with comments. 
308   
309      Args: 
310        from_cache: callable(name, seen), Callable that retrieves an object 
311           prototype for a schema with the given name. Seen is a list of schema 
312           names already seen as we recursively descend the schema definition. 
313   
314      Returns: 
315        Prototype object based on the schema, in Python code with comments. 
316        The lines of the code will all be properly indented. 
317      """ 
318      self.from_cache = from_cache 
319      return self._to_str_impl(self.schema) 
320