envelope¶

Generic serialization of HUGRs and Packages.

The format is designed to be extensible and backwards-compatible. It consists of a header declaring the format used to encode the HUGR, followed by the encoded HUGR itself.

## Payload formats

The envelope may encode the HUGR in different formats, listed in hugr.envelope.EnvelopeFormat. The payload may also be compressed with zstd.

Some formats can be represented as ASCII, as indicated by the hugr.envelope.EnvelopeFormat.ascii_printable() method. When this is the case, the whole envelope can be stored in a string.

## Envelope header

The binary header format is 10 bytes, with the following fields:

Field | Size (bytes) | Description |

|--------|————–|-------------| | Magic | 8 | hugr.envelope.MAGIC_NUMBERS constant identifying the envelope format. | | Format | 1 | hugr.envelope.EnvelopeFormat describing the payload format. | | Flags | 1 | Additional configuration flags. |

Flags:

Bit 0: Whether the payload is compressed with zstd.
Bits 1-5: Reserved for future use.
Bit 7,6: Constant “01” to make some headers ascii-printable.

Functions

`make_envelope`	Encode a HUGR or Package into an envelope, using the given configuration.
`make_envelope_str`	Encode a HUGR or Package into an envelope, using the given configuration.
`read_envelope`	Decode a HUGR package from an envelope.
`read_envelope_hugr`	Decode a HUGR from an envelope.
`read_envelope_hugr_str`	Decode a HUGR from an envelope.
`read_envelope_str`	Decode a HUGR package from an envelope.

Classes

`EnvelopeConfig`	Configuration for writing a HUGR envelope.
`EnvelopeFormat`	Format used to encode a HUGR envelope.
`EnvelopeHeader`	Header of a HUGR envelope.