python/google/appengine/api/yaml_builder.py

   1 #!/usr/bin/env python
   2 #
   3 # Copyright 2007 Google Inc.
   4 #
   5 # Licensed under the Apache License, Version 2.0 (the "License");
   6 # you may not use this file except in compliance with the License.
   7 # You may obtain a copy of the License at
   8 #
   9 #     http://www.apache.org/licenses/LICENSE-2.0
  10 #
  11 # Unless required by applicable law or agreed to in writing, software
  12 # distributed under the License is distributed on an "AS IS" BASIS,
  13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 # See the License for the specific language governing permissions and
  15 # limitations under the License.
  16 #
  17
  18
  19
  20
  21 """PyYAML event builder handler
  22
  23 Receives events from YAML listener and forwards them to a builder
  24 object so that it can construct a properly structured object.
  25 """
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36 from google.appengine.api import yaml_errors
  37 from google.appengine.api import yaml_listener
  38
  39 import yaml
  40
  41
  42 _TOKEN_DOCUMENT = 'document'
  43 _TOKEN_SEQUENCE = 'sequence'
  44 _TOKEN_MAPPING = 'mapping'
  45 _TOKEN_KEY = 'key'
  46 _TOKEN_VALUES = frozenset((
  47   _TOKEN_DOCUMENT,
  48   _TOKEN_SEQUENCE,
  49   _TOKEN_MAPPING,
  50   _TOKEN_KEY))
  51
  52
  53 class Builder(object):
  54   """Interface for building documents and type from YAML events.
  55
  56   Implement this interface to create a new builder.  Builders are
  57   passed to the BuilderHandler and used as a factory and assembler
  58   for creating concrete representations of YAML files.
  59   """
  60
  61   def BuildDocument(self):
  62     """Build new document.
  63
  64     The object built by this method becomes the top level entity
  65     that the builder handler constructs.  The actual type is
  66     determined by the sub-class of the Builder class and can essentially
  67     be any type at all.  This method is always called when the parser
  68     encounters the start of a new document.
  69
  70     Returns:
  71       New object instance representing concrete document which is
  72       returned to user via BuilderHandler.GetResults().
  73     """
  74
  75   def InitializeDocument(self, document, value):
  76     """Initialize document with value from top level of document.
  77
  78     This method is called when the root document element is encountered at
  79     the top level of a YAML document.  It should get called immediately
  80     after BuildDocument.
  81
  82     Receiving the None value indicates the empty document.
  83
  84     Args:
  85       document: Document as constructed in BuildDocument.
  86       value: Scalar value to initialize the document with.
  87     """
  88
  89   def BuildMapping(self, top_value):
  90     """Build a new mapping representation.
  91
  92     Called when StartMapping event received.  Type of object is determined
  93     by Builder sub-class.
  94
  95     Args:
  96       top_value: Object which will be new mappings parant.  Will be object
  97         returned from previous call to BuildMapping or BuildSequence.
  98
  99     Returns:
 100       Instance of new object that represents a mapping type in target model.
 101     """
 102
 103   def EndMapping(self, top_value, mapping):
 104     """Previously constructed mapping scope is at an end.
 105
 106     Called when the end of a mapping block is encountered.  Useful for
 107     additional clean up or end of scope validation.
 108
 109     Args:
 110       top_value: Value which is parent of the mapping.
 111       mapping: Mapping which is at the end of its scope.
 112     """
 113
 114   def BuildSequence(self, top_value):
 115     """Build a new sequence representation.
 116
 117     Called when StartSequence event received.  Type of object is determined
 118     by Builder sub-class.
 119
 120     Args:
 121       top_value: Object which will be new sequences parant.  Will be object
 122         returned from previous call to BuildMapping or BuildSequence.
 123
 124     Returns:
 125       Instance of new object that represents a sequence type in target model.
 126     """
 127
 128   def EndSequence(self, top_value, sequence):
 129     """Previously constructed sequence scope is at an end.
 130
 131     Called when the end of a sequence block is encountered.  Useful for
 132     additional clean up or end of scope validation.
 133
 134     Args:
 135       top_value: Value which is parent of the sequence.
 136       sequence: Sequence which is at the end of its scope.
 137     """
 138
 139   def MapTo(self, subject, key, value):
 140     """Map value to a mapping representation.
 141
 142     Implementation is defined by sub-class of Builder.
 143
 144     Args:
 145       subject: Object that represents mapping.  Value returned from
 146         BuildMapping.
 147       key: Key used to map value to subject.  Can be any scalar value.
 148       value: Value which is mapped to subject. Can be any kind of value.
 149     """
 150
 151   def AppendTo(self, subject, value):
 152     """Append value to a sequence representation.
 153
 154     Implementation is defined by sub-class of Builder.
 155
 156     Args:
 157       subject: Object that represents sequence.  Value returned from
 158         BuildSequence
 159       value: Value to be appended to subject.  Can be any kind of value.
 160     """
 161
 162
 163 class BuilderHandler(yaml_listener.EventHandler):
 164   """PyYAML event handler used to build objects.
 165
 166   Maintains state information as it receives parse events so that object
 167   nesting is maintained.  Uses provided builder object to construct and
 168   assemble objects as it goes.
 169
 170   As it receives events from the YAML parser, it builds a stack of data
 171   representing structural tokens.  As the scope of documents, mappings
 172   and sequences end, those token, value pairs are popped from the top of
 173   the stack so that the original scope can resume processing.
 174
 175   A special case is made for the _KEY token.  It represents a temporary
 176   value which only occurs inside mappings.  It is immediately popped off
 177   the stack when it's associated value is encountered in the parse stream.
 178   It is necessary to do this because the YAML parser does not combine
 179   key and value information in to a single event.
 180   """
 181
 182   def __init__(self, builder):
 183     """Initialization for builder handler.
 184
 185     Args:
 186       builder: Instance of Builder class.
 187
 188     Raises:
 189       ListenerConfigurationError when builder is not a Builder class.
 190     """
 191     if not isinstance(builder, Builder):
 192       raise yaml_errors.ListenerConfigurationError(
 193         'Must provide builder of type yaml_listener.Builder')
 194     self._builder = builder
 195     self._stack = None
 196     self._top = None
 197     self._results = []
 198
 199   def _Push(self, token, value):
 200     """Push values to stack at start of nesting.
 201
 202     When a new object scope is beginning, will push the token (type of scope)
 203     along with the new objects value, the latter of which is provided through
 204     the various build methods of the builder.
 205
 206     Args:
 207       token: Token indicating the type of scope which is being created; must
 208         belong to _TOKEN_VALUES.
 209       value: Value to associate with given token.  Construction of value is
 210         determined by the builder provided to this handler at construction.
 211     """
 212
 213     self._top = (token, value)
 214     self._stack.append(self._top)
 215
 216   def _Pop(self):
 217     """Pop values from stack at end of nesting.
 218
 219     Called to indicate the end of a nested scope.
 220
 221     Returns:
 222       Previously pushed value at the top of the stack.
 223     """
 224     assert self._stack != [] and self._stack is not None
 225     token, value = self._stack.pop()
 226
 227     if self._stack:
 228       self._top = self._stack[-1]
 229     else:
 230       self._top = None
 231     return value
 232
 233   def _HandleAnchor(self, event):
 234     """Handle anchor attached to event.
 235
 236     Currently will raise an error if anchor is used.  Anchors are used to
 237     define a document wide tag to a given value (scalar, mapping or sequence).
 238
 239     Args:
 240       event: Event which may have anchor property set.
 241
 242     Raises:
 243       NotImplementedError if event attempts to use an anchor.
 244     """
 245
 246
 247     if hasattr(event, 'anchor') and event.anchor is not None:
 248       raise NotImplementedError('Anchors not supported in this handler')
 249
 250   def _HandleValue(self, value):
 251     """Handle given value based on state of parser
 252
 253     This method handles the various values that are created by the builder
 254     at the beginning of scope events (such as mappings and sequences) or
 255     when a scalar value is received.
 256
 257     Method is called when handler receives a parser, MappingStart or
 258     SequenceStart.
 259
 260     Args:
 261       value: Value received as scalar value or newly constructed mapping or
 262         sequence instance.
 263
 264     Raises:
 265       InternalError if the building process encounters an unexpected token.
 266       This is an indication of an implementation error in BuilderHandler.
 267     """
 268     token, top_value = self._top
 269
 270
 271
 272     if token == _TOKEN_KEY:
 273
 274       key = self._Pop()
 275
 276       mapping_token, mapping = self._top
 277       assert _TOKEN_MAPPING == mapping_token
 278
 279       self._builder.MapTo(mapping, key, value)
 280
 281
 282
 283
 284
 285     elif token == _TOKEN_MAPPING:
 286       self._Push(_TOKEN_KEY, value)
 287
 288
 289     elif token == _TOKEN_SEQUENCE:
 290       self._builder.AppendTo(top_value, value)
 291
 292
 293
 294     elif token == _TOKEN_DOCUMENT:
 295       self._builder.InitializeDocument(top_value, value)
 296
 297     else:
 298       raise yaml_errors.InternalError('Unrecognized builder token:\n%s' % token)
 299
 300   def StreamStart(self, event, loader):
 301     """Initializes internal state of handler
 302
 303     Args:
 304       event: Ignored.
 305     """
 306     assert self._stack is None
 307     self._stack = []
 308     self._top = None
 309     self._results = []
 310
 311   def StreamEnd(self, event, loader):
 312     """Cleans up internal state of handler after parsing
 313
 314     Args:
 315       event: Ignored.
 316     """
 317     assert self._stack == [] and self._top is None
 318     self._stack = None
 319
 320   def DocumentStart(self, event, loader):
 321     """Build new document.
 322
 323     Pushes new document on to stack.
 324
 325     Args:
 326       event: Ignored.
 327     """
 328     assert self._stack == []
 329     self._Push(_TOKEN_DOCUMENT, self._builder.BuildDocument())
 330
 331   def DocumentEnd(self, event, loader):
 332     """End of document.
 333
 334     Args:
 335       event: Ignored.
 336     """
 337     assert self._top[0] == _TOKEN_DOCUMENT
 338     self._results.append(self._Pop())
 339
 340   def Alias(self, event, loader):
 341     """Not implemented yet.
 342
 343     Args:
 344       event: Ignored.
 345     """
 346     raise NotImplementedError('References not supported in this handler')
 347
 348   def Scalar(self, event, loader):
 349     """Handle scalar value
 350
 351     Since scalars are simple values that are passed directly in by the
 352     parser, handle like any value with no additional processing.
 353
 354     Of course, key values will be handles specially.  A key value is recognized
 355     when the top token is _TOKEN_MAPPING.
 356
 357     Args:
 358       event: Event containing scalar value.
 359     """
 360     self._HandleAnchor(event)
 361     if event.tag is None and self._top[0] != _TOKEN_MAPPING:
 362
 363
 364       try:
 365         tag = loader.resolve(yaml.nodes.ScalarNode,
 366                              event.value, event.implicit)
 367       except IndexError:
 368
 369
 370         tag = loader.DEFAULT_SCALAR_TAG
 371     else:
 372       tag = event.tag
 373
 374     if tag is None:
 375       value = event.value
 376     else:
 377
 378       node = yaml.nodes.ScalarNode(tag,
 379                                    event.value,
 380                                    event.start_mark,
 381                                    event.end_mark,
 382                                    event.style)
 383       value = loader.construct_object(node)
 384     self._HandleValue(value)
 385
 386   def SequenceStart(self, event, loader):
 387     """Start of sequence scope
 388
 389     Create a new sequence from the builder and then handle in the context
 390     of its parent.
 391
 392     Args:
 393       event: SequenceStartEvent generated by loader.
 394       loader: Loader that generated event.
 395     """
 396     self._HandleAnchor(event)
 397     token, parent = self._top
 398
 399
 400     if token == _TOKEN_KEY:
 401       token, parent = self._stack[-2]
 402     sequence = self._builder.BuildSequence(parent)
 403     self._HandleValue(sequence)
 404     self._Push(_TOKEN_SEQUENCE, sequence)
 405
 406   def SequenceEnd(self, event, loader):
 407     """End of sequence.
 408
 409     Args:
 410       event: Ignored
 411       loader: Ignored.
 412       """
 413     assert self._top[0] == _TOKEN_SEQUENCE
 414     end_object = self._Pop()
 415     top_value = self._top[1]
 416     self._builder.EndSequence(top_value, end_object)
 417
 418   def MappingStart(self, event, loader):
 419     """Start of mapping scope.
 420
 421     Create a mapping from builder and then handle in the context of its
 422     parent.
 423
 424     Args:
 425       event: MappingStartEvent generated by loader.
 426       loader: Loader that generated event.
 427     """
 428     self._HandleAnchor(event)
 429     token, parent = self._top
 430
 431
 432
 433
 434
 435
 436     if token == _TOKEN_KEY:
 437       token, parent = self._stack[-2]
 438     mapping = self._builder.BuildMapping(parent)
 439     self._HandleValue(mapping)
 440     self._Push(_TOKEN_MAPPING, mapping)
 441
 442   def MappingEnd(self, event, loader):
 443     """End of mapping
 444
 445     Args:
 446       event: Ignored.
 447       loader: Ignored.
 448     """
 449     assert self._top[0] == _TOKEN_MAPPING
 450     end_object = self._Pop()
 451     top_value = self._top[1]
 452     self._builder.EndMapping(top_value, end_object)
 453
 454   def GetResults(self):
 455     """Get results of document stream processing.
 456
 457     This method can be invoked after fully parsing the entire YAML file
 458     to retrieve constructed contents of YAML file.  Called after EndStream.
 459
 460     Returns:
 461       A tuple of all document objects that were parsed from YAML stream.
 462
 463     Raises:
 464       InternalError if the builder stack is not empty by the end of parsing.
 465     """
 466     if self._stack is not None:
 467       raise yaml_errors.InternalError('Builder stack is not empty.')
 468     return tuple(self._results)