gtirb.serialization module

class gtirb.serialization.BoolCodec[source]

Bases: Codec

A Codec for bool.

static decode(raw_bytes, *, serialization=None, subtypes=(), get_by_uuid=None)[source]

Decode the specified raw data into a Python object.

Parameters:

  • raw_bytes (typing.BinaryIO) – The BytesIO object to be decoded.

  • serialization (typing.Optional[gtirb.serialization.Serialization]) – A Serialization instance used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

  • get_by_uuid (typing.Optional[typing.Callable[[uuid.UUID], typing.Optional[gtirb.node.Node]]]) – A function to look up nodes by UUID.

Return type:

bool

Returns:

A new Python object, as decoded from raw_bytes.

static encode(out, val, *, serialization=None, subtypes=())[source]

Encode an item, writing the serialized object to out.

Parameters:

  • out (typing.BinaryIO) – A binary stream to serialize to.

  • item – The arbitrary Python object to encode.

  • serialization (typing.Optional[gtirb.serialization.Serialization]) – A Serialization instance, used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

Return type:

None

class gtirb.serialization.Codec[source]

Bases: object

The base class for codecs.

static decode(raw_bytes, *, serialization, subtypes, get_by_uuid=None)[source]

Decode the specified raw data into a Python object.

Parameters:

  • raw_bytes (typing.BinaryIO) – The BytesIO object to be decoded.

  • serialization (gtirb.serialization.Serialization) – A Serialization instance used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

  • get_by_uuid (typing.Optional[typing.Callable[[uuid.UUID], typing.Optional[gtirb.node.Node]]]) – A function to look up nodes by UUID.

Return type:

object

Returns:

A new Python object, as decoded from raw_bytes.

static encode(out, item, *, serialization, subtypes)[source]

Encode an item, writing the serialized object to out.

Parameters:

  • out (typing.BinaryIO) – A binary stream to serialize to.

  • item (object) – The arbitrary Python object to encode.

  • serialization (gtirb.serialization.Serialization) – A Serialization instance, used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

Return type:

None

exception gtirb.serialization.CodecError[source]

Bases: Exception

Base class for codec exceptions.

exception gtirb.serialization.DecodeError[source]

Bases: CodecError

An exception during decoding.

exception gtirb.serialization.EncodeError[source]

Bases: CodecError

An exception during encoding.

class gtirb.serialization.Float32Codec[source]

Bases: FloatCodec

bytesize: int = 4
struct_format: str = '<f'
typname: str = 'float'
class gtirb.serialization.Float64Codec[source]

Bases: FloatCodec

bytesize: int = 8
struct_format: str = '<d'
typname: str = 'double'
class gtirb.serialization.FloatCodec[source]

Bases: Codec

Generic base class for float-based Codecs

bytesize: int
classmethod decode(raw_bytes, *, serialization=None, subtypes=(), get_by_uuid=None)[source]

Decode the specified raw data into a Python object.

Parameters:

  • raw_bytes (typing.BinaryIO) – The BytesIO object to be decoded.

  • serialization (typing.Optional[gtirb.serialization.Serialization]) – A Serialization instance used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

  • get_by_uuid (typing.Optional[typing.Callable[[uuid.UUID], typing.Optional[gtirb.node.Node]]]) – A function to look up nodes by UUID.

Return type:

float

Returns:

A new Python object, as decoded from raw_bytes.

classmethod encode(out, val, *, serialization=None, subtypes=())[source]

Encode an item, writing the serialized object to out.

Parameters:

  • out (typing.BinaryIO) – A binary stream to serialize to.

  • item – The arbitrary Python object to encode.

  • serialization (typing.Optional[gtirb.serialization.Serialization]) – A Serialization instance, used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

Return type:

None

struct_format: str
typname: str
class gtirb.serialization.Int16Codec[source]

Bases: IntegerCodec

A Codec for 16-bit signed integers.

bytesize: int = 2
signed: bool = True
typname: str = 'int16_t'
class gtirb.serialization.Int32Codec[source]

Bases: IntegerCodec

A Codec for 32-bit signed integers.

bytesize: int = 4
signed: bool = True
typname: str = 'int32_t'
class gtirb.serialization.Int64Codec[source]

Bases: IntegerCodec

A Codec for 64-bit signed integers.

bytesize: int = 8
signed: bool = True
typname: str = 'int64_t'
class gtirb.serialization.Int8Codec[source]

Bases: IntegerCodec

A Codec for 8-bit signed integers.

bytesize: int = 1
signed: bool = True
typname: str = 'int8_t'
class gtirb.serialization.IntegerCodec[source]

Bases: Codec

Generic base class for integer-based Codecs

bytesize: int
classmethod decode(raw_bytes, *, serialization=None, subtypes=(), get_by_uuid=None)[source]

Decode the specified raw data into a Python object.

Parameters:

  • raw_bytes (typing.BinaryIO) – The BytesIO object to be decoded.

  • serialization (typing.Optional[gtirb.serialization.Serialization]) – A Serialization instance used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

  • get_by_uuid (typing.Optional[typing.Callable[[uuid.UUID], typing.Optional[gtirb.node.Node]]]) – A function to look up nodes by UUID.

Return type:

int

Returns:

A new Python object, as decoded from raw_bytes.

classmethod encode(out, val, *, serialization=None, subtypes=())[source]

Encode an item, writing the serialized object to out.

Parameters:

  • out (typing.BinaryIO) – A binary stream to serialize to.

  • item – The arbitrary Python object to encode.

  • serialization (typing.Optional[gtirb.serialization.Serialization]) – A Serialization instance, used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

Return type:

None

signed: bool
typname: str
class gtirb.serialization.MappingCodec[source]

Bases: Codec

A Codec for mapping<K,V> entries. Implemented via dict.

static decode(raw_bytes, *, serialization, subtypes, get_by_uuid=None)[source]

Decode the specified raw data into a Python object.

Parameters:

  • raw_bytes (typing.BinaryIO) – The BytesIO object to be decoded.

  • serialization (gtirb.serialization.Serialization) – A Serialization instance used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

  • get_by_uuid (typing.Optional[typing.Callable[[uuid.UUID], typing.Optional[gtirb.node.Node]]]) – A function to look up nodes by UUID.

Return type:

typing.Mapping[object, object]

Returns:

A new Python object, as decoded from raw_bytes.

static encode(out, mapping, *, serialization, subtypes)[source]

Encode an item, writing the serialized object to out.

Parameters:

  • out (typing.BinaryIO) – A binary stream to serialize to.

  • item – The arbitrary Python object to encode.

  • serialization (gtirb.serialization.Serialization) – A Serialization instance, used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

Return type:

None

class gtirb.serialization.OffsetCodec[source]

Bases: Codec

A Codec for gtirb.Offset objects, containing a UUID and a displacement.

static decode(raw_bytes, *, serialization=None, subtypes=(), get_by_uuid=None)[source]

Decode the specified raw data into a Python object.

Parameters:

  • raw_bytes (typing.BinaryIO) – The BytesIO object to be decoded.

  • serialization (typing.Optional[gtirb.serialization.Serialization]) – A Serialization instance used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

  • get_by_uuid (typing.Optional[typing.Callable[[uuid.UUID], typing.Optional[gtirb.node.Node]]]) – A function to look up nodes by UUID.

Return type:

gtirb.offset.Offset

Returns:

A new Python object, as decoded from raw_bytes.

static encode(out, val, *, serialization=None, subtypes=())[source]

Encode an item, writing the serialized object to out.

Parameters:

  • out (typing.BinaryIO) – A binary stream to serialize to.

  • item – The arbitrary Python object to encode.

  • serialization (typing.Optional[gtirb.serialization.Serialization]) – A Serialization instance, used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

Return type:

None

class gtirb.serialization.SequenceCodec[source]

Bases: Codec

A Codec for sequence<T> entries. Implemented via list.

static decode(raw_bytes, *, serialization, subtypes, get_by_uuid=None)[source]

Decode the specified raw data into a Python object.

Parameters:

  • raw_bytes (typing.BinaryIO) – The BytesIO object to be decoded.

  • serialization (gtirb.serialization.Serialization) – A Serialization instance used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

  • get_by_uuid (typing.Optional[typing.Callable[[uuid.UUID], typing.Optional[gtirb.node.Node]]]) – A function to look up nodes by UUID.

Return type:

typing.Sequence[object]

Returns:

A new Python object, as decoded from raw_bytes.

static encode(out, sequence, *, serialization, subtypes)[source]

Encode an item, writing the serialized object to out.

Parameters:

  • out (typing.BinaryIO) – A binary stream to serialize to.

  • item – The arbitrary Python object to encode.

  • serialization (gtirb.serialization.Serialization) – A Serialization instance, used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

Return type:

None

class gtirb.serialization.Serialization[source]

Bases: object

Manages codecs used to serialize and deserialize GTIRB objects.

The gtirb.Serialization.decode() method of gtirb.AuxData.serializer is called when GTIRB AuxData is loaded via gtirb.IR.load_protobuf(), and the gtirb.Serialization.encode() method of gtirb.AuxData.serializer is called when GTIRB AuxData is saved to file via gtirb.IR.save_protobuf(). You can alter the encoding and decoding of AuxData values via gtirb.Serialization.codecs. To do this, create a new subclass of gtirb.serialization.Codec and add it to gtirb.Serialization.codecs:

>>> gtirb.AuxData.serializer.codecs['my_custom_type'] = MyCustomCodec

This example registers a new type name, my_custom_type, and associate it with a new codec, MyCustomCodec.

Variables:

~.codecs – A mapping of type names to codecs. Codecs can be added or overridden using this dictionary.

__init__()[source]

Initialize with the built-in gtirb.serialization.Codec subclasses.

decode(raw_bytes, type_name, get_by_uuid=None)[source]

Decode a gtirb.AuxData of the specified type from the specified byte stream.

Parameters:

  • raw_bytes (typing.Union[bytes, bytearray, memoryview, typing.BinaryIO]) – The byte stream from which to read the encoded value.

  • type_name (str) – The type name of the object encoded by raw_bytes.

  • get_by_uuid (typing.Optional[typing.Callable[[uuid.UUID], typing.Optional[gtirb.node.Node]]]) – A function to look up nodes by UUID.

Return type:

object

Returns:

The object encoded by raw_bytes.

encode(out, val, type_name)[source]

Encodes the value of an AuxData value to bytes.

Parameters:

  • out (typing.BinaryIO) – A binary stream to write bytes to.

  • val (object) – The gtirb.AuxData to encode.

  • type_name (str) – The type name of the value encapsulated by the gtirb.AuxData.

Return type:

None

class gtirb.serialization.SetCodec[source]

Bases: Codec

A Codec for set<T> entries. Implemented via set.

static decode(raw_bytes, *, serialization, subtypes, get_by_uuid=None)[source]

Decode the specified raw data into a Python object.

Parameters:

  • raw_bytes (typing.BinaryIO) – The BytesIO object to be decoded.

  • serialization (gtirb.serialization.Serialization) – A Serialization instance used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

  • get_by_uuid (typing.Optional[typing.Callable[[uuid.UUID], typing.Optional[gtirb.node.Node]]]) – A function to look up nodes by UUID.

Return type:

typing.Set[object]

Returns:

A new Python object, as decoded from raw_bytes.

static encode(out, items, *, serialization, subtypes)[source]

Encode an item, writing the serialized object to out.

Parameters:

  • out (typing.BinaryIO) – A binary stream to serialize to.

  • item – The arbitrary Python object to encode.

  • serialization (gtirb.serialization.Serialization) – A Serialization instance, used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

Return type:

None

class gtirb.serialization.StringCodec[source]

Bases: Codec

A Codec for strings.

static decode(raw_bytes, *, serialization=None, subtypes=(), get_by_uuid=None)[source]

Decode the specified raw data into a Python object.

Parameters:

  • raw_bytes (typing.BinaryIO) – The BytesIO object to be decoded.

  • serialization (typing.Optional[gtirb.serialization.Serialization]) – A Serialization instance used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

  • get_by_uuid (typing.Optional[typing.Callable[[uuid.UUID], typing.Optional[gtirb.node.Node]]]) – A function to look up nodes by UUID.

Return type:

str

Returns:

A new Python object, as decoded from raw_bytes.

static encode(out, val, *, serialization=None, subtypes=())[source]

Encode an item, writing the serialized object to out.

Parameters:

  • out (typing.BinaryIO) – A binary stream to serialize to.

  • item – The arbitrary Python object to encode.

  • serialization (typing.Optional[gtirb.serialization.Serialization]) – A Serialization instance, used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

Return type:

None

class gtirb.serialization.SubtypeTree(name, subtypes)[source]

Bases: object

A type hint representing a parsed serialization type name. A SubtypeTree is has two items: A str giving the name of the type and a Sequence of type parameters (which are also SubtypeTrees). For example, the following are all valid SubtypeTrees:

>>> SubtypeTree('string', ())
>>> SubtypeTree('sequence', (SubtypeTree('UUID',()),))
>>> SubtypeTree(
    'mapping', (
        SubtypeTree('string', ()),
        SubtypeTree('set', (SubtypeTree('UUID', ()),))
    )
)
__eq__(other)[source]

Return self==value.

Return type:

bool

__hash__ = None
__init__(name, subtypes)[source]
class gtirb.serialization.TupleCodec[source]

Bases: Codec

A Codec for tuple<…> entries. Implemented via tuple.

static decode(raw_bytes, *, serialization, subtypes, get_by_uuid=None)[source]

Decode the specified raw data into a Python object.

Parameters:

  • raw_bytes (typing.BinaryIO) – The BytesIO object to be decoded.

  • serialization (gtirb.serialization.Serialization) – A Serialization instance used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

  • get_by_uuid (typing.Optional[typing.Callable[[uuid.UUID], typing.Optional[gtirb.node.Node]]]) – A function to look up nodes by UUID.

Return type:

typing.Tuple[object, ...]

Returns:

A new Python object, as decoded from raw_bytes.

static encode(out, items, *, serialization, subtypes)[source]

Encode an item, writing the serialized object to out.

Parameters:

  • out (typing.BinaryIO) – A binary stream to serialize to.

  • item – The arbitrary Python object to encode.

  • serialization (gtirb.serialization.Serialization) – A Serialization instance, used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

Return type:

None

exception gtirb.serialization.TypeNameError(hint)[source]

Bases: EncodeError

A type name is malformed.

__init__(hint)[source]
class gtirb.serialization.UUIDCodec[source]

Bases: Codec

A Codec for raw UUIDs or Nodes.

Decoding a UUID first checks the Node cache for an object with the corresponding UUID, and either returns the object it hits or a new raw UUID.

static decode(raw_bytes, *, serialization=None, subtypes=(), get_by_uuid=None)[source]

Decode the specified raw data into a Python object.

Parameters:

  • raw_bytes (typing.BinaryIO) – The BytesIO object to be decoded.

  • serialization (typing.Optional[gtirb.serialization.Serialization]) – A Serialization instance used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

  • get_by_uuid (typing.Optional[typing.Callable[[uuid.UUID], typing.Optional[gtirb.node.Node]]]) – A function to look up nodes by UUID.

Return type:

typing.Union[uuid.UUID, gtirb.node.Node]

Returns:

A new Python object, as decoded from raw_bytes.

static encode(out, val, *, serialization=None, subtypes=())[source]

Encode an item, writing the serialized object to out.

Parameters:

  • out (typing.BinaryIO) – A binary stream to serialize to.

  • item – The arbitrary Python object to encode.

  • serialization (typing.Optional[gtirb.serialization.Serialization]) – A Serialization instance, used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

Return type:

None

class gtirb.serialization.Uint16Codec[source]

Bases: IntegerCodec

A Codec for 16-bit unsigned integers.

bytesize: int = 2
signed: bool = False
typname: str = 'uint16_t'
class gtirb.serialization.Uint32Codec[source]

Bases: IntegerCodec

A Codec for 32-bit unsigned integers.

bytesize: int = 4
signed: bool = False
typname: str = 'uint32_t'
class gtirb.serialization.Uint64Codec[source]

Bases: IntegerCodec

A Codec for 64-bit unsigned integers.

bytesize: int = 8
signed: bool = False
typname: str = 'uint64_t'
class gtirb.serialization.Uint8Codec[source]

Bases: IntegerCodec

A Codec for 8-bit unsigned integers.

bytesize: int = 1
signed: bool = False
typname: str = 'uint8_t'
exception gtirb.serialization.UnknownCodecError(name)[source]

Bases: CodecError

An unknown codec name is encountered. Caught and handled by the top-level codec methods.

Parameters:

name (str) – the name of the unknown codec

__init__(name)[source]
class gtirb.serialization.UnknownData[source]

Bases: bytes

This class is a blob of bytes representing data with an unknown type. Generated by gtirb.Serialization.decode() when it encounters the name of an unknown codec. Use only at the top level of an auxdata.

class gtirb.serialization.Variant(index, val)[source]

Bases: object

__eq__(other)[source]

Return self==value.

Return type:

bool

__hash__ = None
__init__(index, val)[source]
class gtirb.serialization.VariantCodec[source]

Bases: Codec

A Codec for variant<Ts…> entries.

An encoded record containg two part: index - position of member of variant’s list value - encoded values of selected member

static decode(raw_bytes, *, serialization, subtypes=(), get_by_uuid=None)[source]

Decode the specified raw data into a Python object.

Parameters:

  • raw_bytes (typing.BinaryIO) – The BytesIO object to be decoded.

  • serialization (gtirb.serialization.Serialization) – A Serialization instance used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

  • get_by_uuid (typing.Optional[typing.Callable[[uuid.UUID], typing.Optional[gtirb.node.Node]]]) – A function to look up nodes by UUID.

Return type:

gtirb.serialization.Variant

Returns:

A new Python object, as decoded from raw_bytes.

static encode(out, variant, *, serialization, subtypes=())[source]

Encode an item, writing the serialized object to out.

Parameters:

  • out (typing.BinaryIO) – A binary stream to serialize to.

  • item – The arbitrary Python object to encode.

  • serialization (gtirb.serialization.Serialization) – A Serialization instance, used to invoke other codecs if needed.

  • subtypes (typing.Sequence[gtirb.serialization.SubtypeTree]) – The parsed type of this object.

Return type:

None