afe.ir.serializer.yaml_codec

An encoder/decoder interface for mapping Python objects to data structures that are handled natively by pyyaml. See the documentation on Codec for a more detailed description of details about the interface.

Attributes

`SCALAR_TYPES`
`EncState`
`DecState`
`EncStateV`
`DecStateV`
`ScalarCodecType`
`scalar_codec`
`null_value_codec`
`Fld`

Exceptions

`EncodeError`	An error during YAML encoding due to invalid input or failure to handle the given input.
`DecodeError`	An error during YAML decoding due to invalid input or failure to handle the given input.

Classes

`Codec`	Protocol for an encoder/decoder that converts between a Python object and
`AliasCodec`	Abstract base class for generic types.
`FieldEncoding`	Describes the encoding of one class field as YAML data when encoding a class as a mapping.
`ConstructorEncoding`	An encoding of one class instance as YAML data as part of an encoding scheme for

Functions

`expect_mapping`(→ None)	Verify that the document is a mapping with the given keys, and raise a DecodeError otherwise.
`const_codec`(→ Codec[EncState, DecState, _A])	An encoder that ignores its input and returns a constant value when
`map_codec`(→ Codec[EncState, DecState, _B])	Convert a codec of one type to a codec of another type by applying transformations
`lazy_codec`(→ Codec[EncState, DecState, _A])	Lazily construct a codec.
`enum_codec`(→ Codec[EncState, DecState, _A])	Create a codec for an enum, representing enum values as strings.
`list_codec`(→ Codec[EncState, DecState, List[_A]])	Create a codec for lists.
`homogeneous_tuple_codec`(→ Codec[EncState, DecState, ...)	Create a codec for homogeneous tuples.
`dict_codec`(→ Codec[EncState, DecState, Dict[_A, _B]])	Create a codec for a dict.
`optional_codec`(→ Codec[EncState, DecState, Optional[_A]])	Create a codec for optional values. Since this codec assigns an interpretation to None, the
`named_dict_codec`(→ Codec[EncState, DecState, Dict[str, ...)	Make a codec that encodes a dict having a predetermined set of string keys as a YAML mapping.
`singleton_dict_codec`(→ Codec[EncState, DecState, _A])	Make a codec that puts its encoded value in a YAML mapping. It creates a YAML mapping containing a
`unique_id_codec`(→ Codec[EncState, DecState, int])	Make a codec that encodes unique integer IDs. IDs are encoded as YAML integers.
`unique_id_dec_table`(→ Dict[int, int])	Create a decoder table suitable for use by unique_id_codec.
`aliasable_codec`(→ Codec[EncState, DecState, _A])	Make a codec that applies YAML anchors to encoded data and uses anchors for repeated references to the
`aliasable_codec_enc_table`(→ Dict[int, Any])	Create an encoder table suitable for use by aliasable_codec.
`aliasable_codec_dec_table`(→ Dict[int, Any])	Create a decoder table suitable for use by aliasable_codec.
`intrusive_tagged_union_codec`(→ Codec[EncState, ...)	Make a codec for a union-like type to be encoded as a tagged union.
`type_tagged_codec`(→ Codec[EncState, DecState, _A])	Make a tagged union codec where each tag stands for a distinct type.
`dataclass_style_codec`(→ Codec[EncState, DecState, _A])	Make a codec that translates a class to a mapping with named fields, for classes
`adt_style_codec`(→ Codec[EncState, DecState, _A])	Make a codec for data in the style of an algebraic data type. The decoded data is

Module Contents

afe.ir.serializer.yaml_codec.SCALAR_TYPES[source]

afe.ir.serializer.yaml_codec.EncState[source]

afe.ir.serializer.yaml_codec.DecState[source]

afe.ir.serializer.yaml_codec.EncStateV[source]

afe.ir.serializer.yaml_codec.DecStateV[source]

exception afe.ir.serializer.yaml_codec.EncodeError[source]: An error during YAML encoding due to invalid input or failure to handle the given input.

exception afe.ir.serializer.yaml_codec.DecodeError[source]: An error during YAML decoding due to invalid input or failure to handle the given input.

afe.ir.serializer.yaml_codec.expect_mapping(permitted_keys: Set[str], required_keys: Set[str], doc: Any, context: str) → None[source]

Verify that the document is a mapping with the given keys, and raise a DecodeError otherwise.

Parameters:

permitted_keys – Keys that may be keys of the mapping
required_keys – Keys that must be keys of the mapping. Must be a subset of permitted_keys.
doc – Document to check
context – Description of the document, used in error messages

class afe.ir.serializer.yaml_codec.Codec[source]

Protocol for an encoder/decoder that converts between a Python object and a data structure that pyyaml can natively dump or load.

The encoded form of data must consist of data types that pyyaml handles natively: None, Bool, int, float, str, tuple, list, and dict. Object identity is significant, since Pyyaml uses anchors to de-duplicate multiple references to the same object in the output. A codec may read and write files or other persistent storage on the side.

The encode function converts a Python object to YAML. The decode function does the reverse, and it should behave like the inverse of encode.

Data that is used by encoding or decoding is passed in the ‘state’ parameter. In the intended usage, each type’s codec uses its own mixin-style fields in the state (if it needs any), so that different instances do not interact.

abstract encode(state: EncStateV, obj: _A) → Any[source]

Encode an object to YAML.

Parameters:

state – Encoder state used for encoding
obj – Object to encode

Returns:

Python object suitable for passing to yaml.dump

abstract decode(state: DecStateV, doc: Any) → _A[source]

Decode an object from YAML.

Parameters:

state – Encoder state used for encoding
doc – Python object received from yaml.load to decode

Returns:

Decoded object

afe.ir.serializer.yaml_codec.const_codec(decoded: _A, encoded: Any) → Codec[EncState, DecState, _A][source]

An encoder that ignores its input and returns a constant value when encoding or decoding.

Parameters:

decoded – The constant value to return when decoding.
encoded – The constant value to return when encoding.

Returns:

Constant codec for the given values

afe.ir.serializer.yaml_codec.map_codec(wrap: Callable[[_A], _B], unwrap: Callable[[_B], _A], codec: Codec[EncState, DecState, _A]) → Codec[EncState, DecState, _B][source]

Convert a codec of one type to a codec of another type by applying transformations to the codec’s input and output.

Encoding calls unwrap, then codec.encode. Decoding calls codec.decode, then wrap.

Parameters:

wrap – Transform from the original type to the new one
unwrap – Transform from the new type to the original one
codec – Codec of the underlying type

Returns:

Codec of the new type

afe.ir.serializer.yaml_codec.lazy_codec(thunk: Callable[[], Codec[EncState, DecState, _A]]) → Codec[EncState, DecState, _A][source]

Lazily construct a codec.

This is intended to be used for self-referential codecs that are involved in recursive data structures, like

tree_codec = … lazy_codec(lambda: tree_codec) …

Parameters:: thunk – Thunk that returns a codec
Returns:: Codec that behaves like the thunk’s return value. The thunk is evaluated the first time a method of the codec is called.

afe.ir.serializer.yaml_codec.ScalarCodecType[source]

afe.ir.serializer.yaml_codec.scalar_codec: ScalarCodecType[source]

afe.ir.serializer.yaml_codec.enum_codec(values: Dict[_A, str], description: str) → Codec[EncState, DecState, _A][source]

Create a codec for an enum, representing enum values as strings.

Parameters:

values – Mapping from enum values to strings.
description – A noun phrase describing this data type. It is used in error messages.

Returns:

Codec for enum values.

afe.ir.serializer.yaml_codec.list_codec(item: Codec[EncState, DecState, _A]) → Codec[EncState, DecState, List[_A]][source]

Create a codec for lists.

Parameters:: item – Codec for list elements.
Returns:: Codec for list.

afe.ir.serializer.yaml_codec.homogeneous_tuple_codec(item: Codec[EncState, DecState, _A]) → Codec[EncState, DecState, Tuple[_A, Ellipsis]][source]

Create a codec for homogeneous tuples.

Parameters:: item – Codec for tuple elements.
Returns:: Codec for tuple.

afe.ir.serializer.yaml_codec.dict_codec(key: Codec[EncState, DecState, _A], value: Codec[EncState, DecState, _B]) → Codec[EncState, DecState, Dict[_A, _B]][source]

Create a codec for a dict.

Parameters:

key – Codec for dict keys
value – Codec for dict values

Returns:

Codec for dict

afe.ir.serializer.yaml_codec.optional_codec(item: Codec[EncState, DecState, _A]) → Codec[EncState, DecState, _A | None][source]

Create a codec for optional values. Since this codec assigns an interpretation to None, the given codec should not interpret None.

Parameters:: item – Codec for values.
Returns:: Codec for optional values.

afe.ir.serializer.yaml_codec.null_value_codec[source]

afe.ir.serializer.yaml_codec.named_dict_codec(index: Dict[str, Codec], description: str, *, defaults: Dict[str, Any] = {}) → Codec[EncState, DecState, Dict[str, Any]][source]

Make a codec that encodes a dict having a predetermined set of string keys as a YAML mapping. This is a typical way of encoding Python class instances.

This codec encodes and decodes Python dictionaries having the same keys as ‘index’. Each dict item is encoded and decoded using the codec for that key in ‘index’. The ‘defaults’ dict provides default values for the encoding. When an item compares equal to a default value, it is omitted from YAML. Missing items in YAML are materialized using the default value.

For example, consider the following codec.

c = named_dict_codec({'name': scalar_codec, 'quantity': scalar_codec}, defaults = {'quantity': 1})

Calling c.encode({‘name’: ‘x’, ‘quantity’: 1}) returns {‘name’: ‘x’}.

Fields are optional only in the encoded form. All fields are required in the decoded form.

Parameters:

index – A mapping from strings to codecs. Encoded dicts must have the same keys as this mapping, and their values are encoded or decoded using these codecs.
description – A noun phrase describing this data type. It is used in error messages.
defaults – Default values for items in the index. If a default value is given, items matching that value (when compared using __eq__) are omitted in the encoded form.

Returns:

Codec for dicts

afe.ir.serializer.yaml_codec.singleton_dict_codec(key: str, codec: Codec[EncState, DecState, _A], description: str) → Codec[EncState, DecState, _A][source]

Make a codec that puts its encoded value in a YAML mapping. It creates a YAML mapping containing a single item. This is useful when combined with other codecs.

Suppose there is a codec c, and c.encode(x) returns y. Then, singleton_dict_codec(‘data’, c).encode(x) returns {‘data’: y}. That contains the same result as the original codec, wrapped in a mapping.

Parameters:

key – Key to use in the YAML mapping
codec – Codec for the value
description – A noun phrase describing this data type. It is used in error messages.

Returns:

Codec that wraps the encoded value in a mapping

afe.ir.serializer.yaml_codec.unique_id_codec(make_new_id: Callable[[], int], get_dec_table: Callable[[DecState], Dict[int, int]]) → Codec[EncState, DecState, int][source]

Make a codec that encodes unique integer IDs. IDs are encoded as YAML integers. IDs are converted to new values when they are decoded so that the result is unique after decoding.

Parameters:

make_new_id – How to make a new unique ID. This is called during decoding for every ID that appears in the YAML document.
get_dec_table – Get decoder state for this codec to use and modify. The state should be initialized by calling unique_id_dec_table.

Returns:

codec for unique integer IDs.

afe.ir.serializer.yaml_codec.unique_id_dec_table() → Dict[int, int][source]: Create a decoder table suitable for use by unique_id_codec.

class afe.ir.serializer.yaml_codec.AliasCodec(get_enc_table: Callable[[EncState], Dict[int, Any]], get_dec_table: Callable[[DecState], Dict[int, Any]], codec: Codec[EncState, DecState, _A])[source]

Abstract base class for generic types.

A generic type is typically declared by inheriting from this class parameterized with one or more type variables. For example, a generic mapping type might be defined as:

class Mapping(Generic[KT, VT]):
    def __getitem__(self, key: KT) -> VT:
        ...
    # Etc.

This class can then be used as follows:

def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
    try:
        return mapping[key]
    except KeyError:
        return default

encode(state: EncState, obj: _A) → Any[source]

decode(state: DecState, doc: Any) → _A[source]

afe.ir.serializer.yaml_codec.aliasable_codec(get_enc_table: Callable[[EncState], Dict[int, Any]], get_dec_table: Callable[[DecState], Dict[int, Any]], codec: Codec[EncState, DecState, _A]) → Codec[EncState, DecState, _A][source]

Make a codec that applies YAML anchors to encoded data and uses anchors for repeated references to the same object. An object will be encoded at most once and will be recreated once during decoding, no matter how many times it appears.

This is done by memoizing the encoded representation so that the yaml library will use anchors. Thus, it depends on the yaml library to use anchors and memoization when the yaml library encounters the same object in its input.

Parameters:

get_enc_table – Get encoder state for this codec to use and modify. The state should be initialized by calling aliasable_codec_enc_table.
get_dec_table – Get decoder state for this codec to use and modify. The state should be initialized by calling aliasable_codec_dec_table.
codec – Codec to extend with aliasing

Returns:

Codec that uses anchors for aliasing

afe.ir.serializer.yaml_codec.aliasable_codec_enc_table() → Dict[int, Any][source]: Create an encoder table suitable for use by aliasable_codec.

afe.ir.serializer.yaml_codec.aliasable_codec_dec_table() → Dict[int, Any][source]: Create a decoder table suitable for use by aliasable_codec.

afe.ir.serializer.yaml_codec.intrusive_tagged_union_codec(tag_name: str, codecs: Dict[str, Codec[EncState, DecState, _A]], get_tag: Callable[[_A], str]) → Codec[EncState, DecState, _A][source]

Make a codec for a union-like type to be encoded as a tagged union.

The encoding is a YAML mapping, where one key in the mapping has a string tag and the other keys are tag-dependent. For example, consider the following codec for Union[int, str].

value_codec = singleton_dict_codec('number', scalar_codec)
info_codec = singleton_dict_codec('message', scalar_codec)
def get_tag(x):
    return 'info' if isinstance(x, str) else 'value'
c = intrusive_tagged_union_codec('type', {'value': value_codec, 'info': message_codec}, get_tag)

Calling c.encode(3) returns {‘type’: ‘value’, ‘number’: 3}. Calling c.encode(‘Three’) returns {‘type’: ‘info’, ‘message’: ‘Three’}. The dict key ‘type’ is the tag indicating which union member it is. The other keys hold the rest of the data.

Parameters:

tag_name – Name of the tag in encoded YAML mappings.
codecs – Alternative codecs, indexed by tag.
get_tag – Selects which codec to use for encoding a value.

Returns:

Codec for the tagged union

afe.ir.serializer.yaml_codec.type_tagged_codec(tag_name: str, codecs: Sequence[Tuple[str, type, Codec[EncState, DecState, _A]]]) → Codec[EncState, DecState, _A][source]

Make a tagged union codec where each tag stands for a distinct type.

Parameters:: codecs – Tag, type, and codec of each alternative encoding.
Returns:: Codec for the tagged union

class afe.ir.serializer.yaml_codec.FieldEncoding[source]

Describes the encoding of one class field as YAML data when encoding a class as a mapping.

Parameters:

python_name – Name of the field in Python source code.
yaml_name – Name of the field in a YAML mapping.
codec – Encoding of the field’s value.
default – Field’s default value, used if the field is omitted in the YAML mapping.

python_name: str[source]

yaml_name: str[source]

codec: Codec[EncState, DecState, Any][source]

default: Any[source]

afe.ir.serializer.yaml_codec.Fld[source]

afe.ir.serializer.yaml_codec.dataclass_style_codec(cls: type, fields: Sequence[FieldEncoding]) → Codec[EncState, DecState, _A][source]

Make a codec that translates a class to a mapping with named fields, for classes that resemble dataclasses. To use this codec, a class must have a dataclass-style constructor so that it’s possible to clone with this pattern of field accesses and constructor call:

copy_of_instance = MyClass(instance.field1, instance.field2, instance.field3)

Python reflection is used to access fields by name.

Parameters:

cls – The Python class to create the codec for
fields – The class’s fields

Returns:

Codec for the class

class afe.ir.serializer.yaml_codec.ConstructorEncoding[source]

An encoding of one class instance as YAML data as part of an encoding scheme for algebraic data types.

If a sequence of one or more field encodings is given, a dataclass_style_codec encoding is used.
If an empty sequence is given, a const_codec encoding is used.
If a codec is given, the codec is used to encode an instance of the class. Its encoded form must be a mapping. The algebraic data type tag will be injected into the mapping.

Parameters:

cls – The Python class that this constructor represents
yaml_name – The string used to represent that class in YAML
fields – Encoding of the class’s fields. Either a list giving the encoding of each field, or a Codec giving the encoding of an entire class instance as a YAML mapping.

cls: type[source]

yaml_name: str[source]

fields: Sequence[FieldEncoding] | Codec[EncState, DecState, Any][source]

afe.ir.serializer.yaml_codec.adt_style_codec(tag_name: str, members: Sequence[ConstructorEncoding]) → Codec[EncState, DecState, _A][source]

Make a codec for data in the style of an algebraic data type. The decoded data is a union of the types given in members. The encoded data is a mapping constructed with intrusive_tagged_union_codec. It has a tag indicating which type is encoded there.

Parameters:

tag_name – The name of the type tag in the encoded dict.
members – The members of the data type. An instance of the type is an instance of one member.

Returns:

Codec for the type.