Package

class hugr.package.Package(modules: list[Hugr], extensions: list[Extension] = <factory>)

Bases: object

A package of HUGR modules and extensions.

The HUGRs may refer to the included extensions or those not included.

Methods

from_bytes	Deserialize a byte string to a Package object.
from_json	Deserialize a JSON string to a Package object.
from_model	Deserialize a hugr model to a Package object.
from_str	Deserialize a string to a Package object.
link	Link this package with other packages, returning a new package containing the extensions of all packages, as well as a single module created from linking the modules from all packages.
resolve_extensions	Resolve extension references in the types and operations of the package.
to_bytes	Serialize the package to a HUGR envelope byte string.
to_json	Serialize the package to a printable HUGR envelope string.
to_model	Export the package as its hugr model representation.
to_str	Serialize the package to a HUGR envelope string.
used_extensions	Get the extensions used by this Package, optionally resolving unresolved types and operations.

Attributes

modules	HUGR modules in the package.
extensions	Extensions included in the package.

extensions: list[Extension]

Extensions included in the package.

static from_bytes(envelope: bytes, extensions: ExtensionRegistry | None = None) → Package

Deserialize a byte string to a Package object.

Some envelope formats can be read from a string. See from_str().

Parameters:

• envelope – The byte string representing a Package.

• extensions – If not None, an extension registry to resolve the custom operations and types.

Returns:

The deserialized Package object.

classmethod from_json(json_str: str) → Package

Deserialize a JSON string to a Package object.

Parameters:

json_str – The JSON string representing a Package.

Returns:

The deserialized Package object.

static from_model(package: model.Package, extensions: list[Extension] | None = None, *, resolve_from: ExtensionRegistry | None = None)

Deserialize a hugr model to a Package object.

Parameters:

• package – The hugr model representing a Package.

• extensions – If not None, the extensions to include in the package.

• resolve_from – If not None, an extension registry to resolve the custom operations and types. Defaults to the standard extensions, plus any extensions included in the package.

static from_str(envelope: str, extensions: ExtensionRegistry | None = None) → Package

Deserialize a string to a Package object.

Not all envelope formats can be read from a string. See from_bytes() for a more general method.

Parameters:

• envelope – The string representing a Package.

• extensions – If not None, an extension registry to resolve the custom operations and types.

Returns:

The deserialized Package object.

link(*other: Package)

Link this package with other packages, returning a new package containing the extensions of all packages, as well as a single module created from linking the modules from all packages.

Parameters:

*other – Other packages to link with.

Returns:

A new package containing the modules and extensions of all packages.

modules: list[Hugr]

HUGR modules in the package.

resolve_extensions(registry: ExtensionRegistry) → Package

Resolve extension references in the types and operations of the package.

This method modifies the HUGR modules and packaged extensions in-place, replacing Custom operations with ExtOp operations and opaque types with ExtType when their extensions are found in the registry.

This is an alias for used_extensions() that discards the computed extensions.

Parameters:

registry – The extension registry to resolve against.

to_bytes(config: EnvelopeConfig | None = None) → bytes

Serialize the package to a HUGR envelope byte string.

Some envelope formats can be encoded into a string. See to_str().

to_json() → str

Serialize the package to a printable HUGR envelope string.

to_model() → Package

Export the package as its hugr model representation.

At the moment this does not yet contain the extensions.

to_str(config: EnvelopeConfig | None = None) → str

Serialize the package to a HUGR envelope string.

Not all envelope formats can be encoded into a string. See to_bytes() for a more general method.

used_extensions(resolve_from: ExtensionRegistry | None = None) → ExtensionResolutionResult

Get the extensions used by this Package, optionally resolving unresolved types and operations.

This method modifies the HUGR modules and packaged extensions in-place when resolve_from is provided, replacing Custom operations with ExtOp operations and opaque types with ExtType when their extensions are found in the registry.

Parameters:

resolve_from – Optional extension registry to resolve against. If None, opaque types and Custom ops will not be resolved.

Returns:

The result of resolving the extensions, containing the used extensions and a list of referenced but unresolved extensions.

Example

>>> from hugr.build import Dfg
>>> Dfg(tys.Qubit).hugr.used_extensions().ids()
{'prelude'}