YAML Serialisation (pytyp.s11n.yaml)

This module extends the popular PyYAML library so that it can write and return instances of Python classes. This simplifies Python code that interacts with YAML (you don’t need to use dicts where you would normally use a class, which means you can access values using attributes rather than named indices).

Warning

This module requires PyYAML. If that package is not present then the functionality defined here will not be available.

Encoding

Tip

For background details see Encoding Support and Type Specifications (pytyp.spec.abcs).

pytyp.s11n.yaml.dump(data, stream=None, **kargs)

Serialize data as a YAML formatted stream (or return a string).

Parameters:

• data – The Python object (or collection) to encode.
• stream – The destination for the data.
• kargs – Additional parameters are passed directly to the corresponding routine in pyyaml.

Returns:

A string containing YAML encoded data if stream is None; otherwise None (output written to stream).

Here is an example of encoding a Python class, and then reading that back from YAML:

>>> class Example():
...     def __init__(self, foo):
...         self.foo = foo
...     def __repr__(self):
...         return '<Example({0})>'.format(self.foo)
>>> dump(Example('abc'))
'{foo: abc}\n'
>>> load = make_load(Example)
>>> load('{foo: abc}')
<Example(abc)>

pytyp.s11n.yaml.dump_all(data, stream=None, **kargs)

Serialize a sequence of values as a YAML formatted stream (or return a string).

Parameters:

• data – A generators of Python values.
• stream – The destination for the data.
• kargs – Additional parameters are passed directly to the corresponding routine in pyyaml.

Returns:

A string containing YAML encoded data if stream is None; otherwise None (output written to stream).

Here is an example of encoding a series of Python classes, and then reading that back from YAML:

>>> class Example():
...     def __init__(self, foo):
...         self.foo = foo
...     def __repr__(self):
...         return '<Example({0})>'.format(self.foo)
>>> dump_all([Example('abc'), Example('xyz')])
'{foo: abc}\n--- {foo: xyz}\n'
>>> load_all = make_load_all([Example, Example])
>>> list(load_all('{foo: abc}\n--- {foo: xyz}\n'))
[<Example(abc)>, <Example(xyz)>]

Note

The _all() routines work with YAML’s support for multiple documents. Each document is handled separately and the list [Example, Example] above, as an argument to make_load_all(), is not a type specification, but an iterable collection of type specifications, one per document.

Decoding

Tip

For background details see Decoding Support and Type Specifications (pytyp.spec.abcs).

pytyp.s11n.yaml.make_load(spec)

Create a replacement for the load() function in pyyaml that will deserialize a stream containing a YAML document to a Python object.

Parameters:spec – The type specification for the root object. Nested objects are defined by type annotations. See Decoding Support for full details. Returns:A replacement for load() in the PyYAML package which returns data structure as spec.

The documentation for dump() above contains an example of use.

pytyp.s11n.yaml.make_load_all(spec)

Create a replacement for the load_all() function in pyyaml that will deserialize a stream containing multiple YAML documents to Python objects.

Parameters:spec – A generator giving type specifications for the root objects. Nested objects are defined by type annotations. See Decoding Support for full details. Returns:A replacement for load_all() in the PyYAML package which returns data structure as spec.

The documentation for dump_all() above contains an example of use.