python_pae.encode module

This module defines helper functions and coroutines for encoding and decoding PAE values.

python_pae.encode.marshal(value: python_pae.encode.T, pae_type: python_pae.abstract.PAEType[python_pae.encode.T]) → bytes

Serialise a value into bytes.

Parameters

  • value – The value to be processed.

  • pae_type – The PAEType that provides the serialisation logic.

Returns

A byte string representing the value passed in.

python_pae.encode.unmarshal(packed: bytes, pae_type: python_pae.abstract.PAEType[python_pae.encode.T]) → python_pae.encode.T

Decode a byte string back into a value. Inverse operation of marshal().

Parameters

  • packed – The byte string to be processed.

  • pae_type – The PAEType that provides the deserialisation logic.

Returns

A decoded value.

Raises

python_pae.PAEDecodeError – if an error occurs in the decoding process.

python_pae.encode.write_prefixed(value: python_pae.encode.T, pae_type: python_pae.abstract.PAEType[python_pae.encode.T], stream: IO, length_type: python_pae.number.PAENumberType, prefix_if_constant: bool = True) → int

Write a value to a stream, prefixed with the length of the serialised payload.

Note

The output stream must be seekable for this to work.

Parameters

  • value – The value to write.

  • pae_type – The PAEType that provides the serialisation logic.

  • stream – The output stream to write to.

  • length_type – Numeric type to use for the length prefix.

  • prefix_if_constant – Flag toggling whether to apply the length prefix if the type being written is a fixed-width type. Defaults to True.

Returns

The number of bytes written (including the length prefix, if present).

python_pae.encode.read_prefixed_coro(pae_type: python_pae.abstract.PAEType[python_pae.encode.T], stream: IO, length_type: python_pae.number.PAENumberType, prefix_if_constant: bool = True)

Coroutine that reads and parses a length-prefixed value. The coroutine yields at most twice. First, the expected length is yielded. Next, the value is decoded and yielded.

Note

The idea is that the caller can abort the parse based on the length value.

Parameters

  • pae_type – The PAEType that provides the deserialisation logic.

  • stream – The stream to read from.

  • length_type – Numeric type to use for the length prefix.

  • prefix_if_constant – Flag toggling whether to expect a length prefix if the type being read is a fixed-width type. Defaults to True.

Raises

python_pae.PAEDecodeError – if an error occurs in the decoding process.

Returns

A generator object.

python_pae.encode.read_pae_coro(stream: IO, settings: python_pae.encode.PAEListSettings, expected_length=None)

Coroutine to read a (possibly heterogeneous) PAE-encoded list.

The protocol is as follows:

  1. First, the coroutine parses and yields the number of list elements.

  2. Then, the caller should .send() in a PAEType object, after which the coroutine will yield a value.

  3. Repeat step 2 for each element of the list.

The coroutine-based approach allows for a degree of freedom in the schema (e.g. optional fields), while still parsing on an on-demand basis.

Parameters

  • stream – The stream to read from.

  • settings – List encoding settings.

  • expected_length – The expected byte length of the encoded list payload. If None, the length is not enforced.

Raises

python_pae.PAEDecodeError – if an error occurs in the decoding process.

Returns

A generator object.

class python_pae.encode.PAEListSettings(size_type: python_pae.number.PAENumberType = <uint64 (ULLONG)>, length_type: Optional[python_pae.number.PAENumberType] = None, prefix_if_constant: bool = True)

Bases: object

List encoding settings. The defaults represent the PASETO version of PAE.

size_type: python_pae.number.PAENumberType = <uint64 (ULLONG)>

Numeric type to use for the list size.

Note

The default is a 64-bit integer for compatibility with PASETO PAE.

length_type: Optional[python_pae.number.PAENumberType] = None

Numeric type to use for the length prefixes of the list items.

Note

If unspecified, will be the same as size_type.

prefix_if_constant: bool = True

Flag toggling whether to apply the length prefix if the type being written or read is a fixed-width type. Defaults to True.