ppsc.parse package

A package to support the (de)serialization of phenopacket schema elements to/from various formats, such as JSON, YAML, and protobuf.

class ppsc.parse.Serializer

Bases: object

Serializer serializes a Serializable object into a format such as JSON, YAML, or others.

The format depends on the serializer subclass.

abstract serialize(val: Serializable, fp: IO)

Serialize a value val into the provided IO object fp.

class ppsc.parse.Serializable

Bases: object

Serializable is a mixin class for data classes composed of a hierarchy of primitive types, such as bool, int, float, or str, or other Serializable objects.

Serializable knows how to convert the data into a hierarchy composed of primitive types or Python compound types such as list and dict. The hierarchy is an intermediate step before serializing into a data format such as JSON, YAML or others using a :class:Serializer`.

The mixin requirements include a single method: field_names() and the other functionality then comes for free.

abstract static field_names() → Iterable[str]

Get an iterable with the data class field names.

to_dict(out: MutableMapping[str, Any])

Write itself into a dictionary composed of primitive or Python compound types.

class ppsc.parse.Deserializer

Bases: object

Deserializer decodes a Deserializable class from a str or text IO handle.

abstract deserialize(fp: str | TextIOBase, clz: Type[D]) → D

Decode an instance of deserializable class from the input fp.

Parameters:

• fp – input to decode either as a str or a text IO handle.

• clz – type of the class to be created from the input.

Returns:

a new instance of D with attributes set based on the fp.

class ppsc.parse.Deserializable

Bases: object

Deserializable knows how to initialize itself based on a dict with intermediate Python representation.

See Serializable for more info.

abstract classmethod from_dict(values: Mapping[str, Any])

abstract classmethod required_fields() → Sequence[str]

class ppsc.parse.FromProtobuf

Bases: object

A mixin for data classes/types that can be created from some protobuf bytes.

In general, the deserialization first constructs an intermediate Protobuf Message. The message is then mapped into the actual class.

Example

Let’s load example protobuf file at the following location:

>>> import os
>>> fpath_pb = os.path.join('tests', 'data', 'pp', 'retinoblastoma.pb')

The file contains a v2.0.2 phenopacket. Let’s import the Phenopacket class and load the file:

>>> from ppsc.v202 import Phenopacket
>>> with open(fpath_pb, 'rb') as fh:
...   pp = Phenopacket.from_pb(fh)

Now we have a phenopacket that we can work with:

>>> pp.id
'example.retinoblastoma.phenopacket.id'

abstract classmethod message_type() → Type[Message]

Get the type of the protobuf element that this class can be decoded from.

abstract classmethod from_message(msg: Message)

Decode the message into a new instance of this class.

classmethod from_pb(fp: BinaryIO)

Create an instance from some bytes read from pb. The bytes are expected to correspond to the state of the message.

classmethod complain_about_incompatible_msg_type(msg: Message)

A utility method for user-friendly complaint regarding attempting to decode from incompatible type.

class ppsc.parse.ToProtobuf

Bases: object

A mixin for data classes that can encode themselves into some protobuf bytes.

Example

Let’s create an example subject:

>>> from ppsc.v202 import Individual
>>> i = Individual(id='example.id', alternate_ids=['other', 'identifiers'])

Now we can serialize the individual into a file or, for the purpose of this test, into io.BytesIO buffer:

>>> import io
>>> buf = io.BytesIO()

>>> i.dump_pb(buf)

>>> buf.getvalue()
b'\n\nexample.id\x12\x05other\x12\x0bidentifiers'

abstract to_message() → Message

Get a protobuf representation of the class.

dump_pb(fp: BinaryIO)

Write the protobuf representation of the class into the provided fp byte handle.

Subpackages

• ppsc.parse.json package
  • JsonSerializer
  • JsonDeserializer