google.appengine.api.yaml_builder module

Summary

PyYAML event builder handler

Receives events from YAML listener and forwards them to a builder object so that it can construct a properly structured object.

Contents

class google.appengine.api.yaml_builder.Buildersource

Bases: object

Interface for building documents and type from YAML events.

Implement this interface to create a new builder. Builders are passed to the BuilderHandler and used as a factory and assembler for creating concrete representations of YAML files.

AppendTo(subject, value)source

Append value to a sequence representation.

Implementation is defined by sub-class of Builder.

Parameters

• subject – Object that represents sequence. Value returned from BuildSequence

• value – Value to be appended to subject. Can be any kind of value.

BuildDocument()source

Build new document.

The object built by this method becomes the top level entity that the builder handler constructs. The actual type is determined by the sub-class of the Builder class and can essentially be any type at all. This method is always called when the parser encounters the start of a new document.

Returns

New object instance representing concrete document which is returned to user via BuilderHandler.GetResults().

BuildMapping(top_value)source

Build a new mapping representation.

Called when StartMapping event received. Type of object is determined by Builder sub-class.

Parameters

top_value – Object which will be new mappings parant. Will be object returned from previous call to BuildMapping or BuildSequence.

Returns

Instance of new object that represents a mapping type in target model.

BuildSequence(top_value)source

Build a new sequence representation.

Called when StartSequence event received. Type of object is determined by Builder sub-class.

Parameters

top_value – Object which will be new sequences parant. Will be object returned from previous call to BuildMapping or BuildSequence.

Returns

Instance of new object that represents a sequence type in target model.

EndMapping(top_value, mapping)source

Previously constructed mapping scope is at an end.

Called when the end of a mapping block is encountered. Useful for additional clean up or end of scope validation.

Parameters

• top_value – Value which is parent of the mapping.

• mapping – Mapping which is at the end of its scope.

EndSequence(top_value, sequence)source

Previously constructed sequence scope is at an end.

Called when the end of a sequence block is encountered. Useful for additional clean up or end of scope validation.

Parameters

• top_value – Value which is parent of the sequence.

• sequence – Sequence which is at the end of its scope.

InitializeDocument(document, value)source

Initialize document with value from top level of document.

This method is called when the root document element is encountered at the top level of a YAML document. It should get called immediately after BuildDocument.

Receiving the None value indicates the empty document.

Parameters

• document – Document as constructed in BuildDocument.

• value – Scalar value to initialize the document with.

MapTo(subject, key, value)source

Map value to a mapping representation.

Implementation is defined by sub-class of Builder.

Parameters

• subject – Object that represents mapping. Value returned from BuildMapping.

• key – Key used to map value to subject. Can be any scalar value.

• value – Value which is mapped to subject. Can be any kind of value.

class google.appengine.api.yaml_builder.BuilderHandler(builder)source

Bases: google.appengine.api.yaml_listener.EventHandler

PyYAML event handler used to build objects.

Maintains state information as it receives parse events so that object nesting is maintained. Uses provided builder object to construct and assemble objects as it goes.

As it receives events from the YAML parser, it builds a stack of data representing structural tokens. As the scope of documents, mappings and sequences end, those token, value pairs are popped from the top of the stack so that the original scope can resume processing.

A special case is made for the _KEY token. It represents a temporary value which only occurs inside mappings. It is immediately popped off the stack when it’s associated value is encountered in the parse stream. It is necessary to do this because the YAML parser does not combine key and value information in to a single event.

Alias(event, loader)source

Not implemented yet.

Parameters

event – Ignored.

DocumentEnd(event, loader)source

End of document.

Parameters

event – Ignored.

DocumentStart(event, loader)source

Build new document.

Pushes new document on to stack.

Parameters

event – Ignored.

GetResults()source

Get results of document stream processing.

This method can be invoked after fully parsing the entire YAML file to retrieve constructed contents of YAML file. Called after EndStream.

Returns

A tuple of all document objects that were parsed from YAML stream.

Raises

InternalError if the builder stack is not empty by the end of parsing.

MappingEnd(event, loader)source

End of mapping

Parameters

• event – Ignored.

• loader – Ignored.

MappingStart(event, loader)source

Start of mapping scope.

Create a mapping from builder and then handle in the context of its parent.

Parameters

• event – MappingStartEvent generated by loader.

• loader – Loader that generated event.

Scalar(event, loader)source

Handle scalar value

Since scalars are simple values that are passed directly in by the parser, handle like any value with no additional processing.

Of course, key values will be handles specially. A key value is recognized when the top token is _TOKEN_MAPPING.

Parameters

event – Event containing scalar value.

SequenceEnd(event, loader)source

End of sequence.

Parameters

• event – Ignored

• loader – Ignored.

SequenceStart(event, loader)source

Start of sequence scope

Create a new sequence from the builder and then handle in the context of its parent.

Parameters

• event – SequenceStartEvent generated by loader.

• loader – Loader that generated event.

StreamEnd(event, loader)source

Cleans up internal state of handler after parsing

Parameters

event – Ignored.

StreamStart(event, loader)source

Initializes internal state of handler

Parameters

event – Ignored.