dazl

dazl.damast

The dazl.damlast package contains types and functions for working with Daml-LF Archives. The types in this module are for dealing with Daml’s type system as encoded in Daml-LF; for encoding and decoding of values, see dazl.values.

dazl.damlast.daml_lf_1:

The full definition of a Daml-LF Archive.

dazl.damlast.daml_types:

Convenience functions for constructing Daml Type objects.

dazl.damlast.lookup:

Utilities for quickly resolving names to Daml-LF types/values.

dazl.damlast.parse:

Functions for parsing a Daml-LF Archive from its Protobuf definition.

dazl.damlast.protocols:

Protocols (interfaces) for components in this package.

dazl.damlast.errors:

Subclasses of Error that may be thrown by classes in this package.

DAML-LF Archive types

members

DAML Types

Constants and constructor functions for the various primitive DAML types.

dazl.damlast.daml_types.Arrow(a: dazl.damlast.daml_lf_1.Type, b: dazl.damlast.daml_lf_1.Type) dazl.damlast.daml_lf_1.Type

Construct a DAML Type that is equivalent to a -> b (a function type).

This type is not normally used in dazl since we are primarily concerned with serializable types; it is included for completeness.

dazl.damlast.daml_types.ContractId(a: dazl.damlast.daml_lf_1.Type) dazl.damlast.daml_lf_1.Type

Construct a DAML Type that is equivalent to ContractId a.

No checking is done to verify that the argument refers to a valid template.

dazl.damlast.daml_types.List(a: dazl.damlast.daml_lf_1.Type) dazl.damlast.daml_lf_1.Type

Construct a DAML Type that is equivalent to [a] (a list of objects).

dazl.damlast.daml_types.Map(k: dazl.damlast.daml_lf_1.Type, v: dazl.damlast.daml_lf_1.Type) dazl.damlast.daml_lf_1.Type

Construct a DAML Type that is equivalent to Map k v.

dazl.damlast.daml_types.Numeric(n: int) dazl.damlast.daml_lf_1.Type

Construct a DAML Type that is equivalent to Numeric n.

dazl.damlast.daml_types.Optional(a: dazl.damlast.daml_lf_1.Type) dazl.damlast.daml_lf_1.Type

Construct a DAML Type that is equivalent to Optional a (either Some a or None).

dazl.damlast.daml_types.Scenario(a: dazl.damlast.daml_lf_1.Type) dazl.damlast.daml_lf_1.Type

Construct a DAML Type that is equivalent to Scenario a.

This type is not normally used in dazl since we are primarily concerned with serializable types; it is included for completeness.

dazl.damlast.daml_types.TextMap(a: dazl.damlast.daml_lf_1.Type) dazl.damlast.daml_lf_1.Type

Construct a DAML Type that is equivalent to TextMap a.

dazl.damlast.daml_types.Update(a: dazl.damlast.daml_lf_1.Type) dazl.damlast.daml_lf_1.Type

Construct a DAML Type that is equivalent to Update a.

This type is not normally used in dazl since we are primarily concerned with serializable types; it is included for completeness.

dazl.damlast.daml_types.con(tycon: dazl.damlast.daml_lf_1.TypeConName, *args: dazl.damlast.daml_lf_1.Type) dazl.damlast.daml_lf_1.Type

Construct a DAML Type that is a reference to a DefDataType (a record, variant, or enum).

Parameters
  • tycon – The fully-qualified name of the type constructor.

  • args – Type arguments (only applicable if the type is a generic type).

dazl.damlast.daml_types.struct(fields: Mapping[str, dazl.damlast.daml_lf_1.Type])

Construct a DAML Type that is equivalent to a structural tuple type ((a, b, ...)).

Parameters

fields – A map of field names to their types. DAML-LF structs generally define structs as having field names "_1", "_2", "_3", and so on.

dazl.damlast.daml_types.syn(tysyn: dazl.damlast.daml_lf_1.TypeSynName, *args: dazl.damlast.daml_lf_1.Type) dazl.damlast.daml_lf_1.Type

Construct a DAML Type that is a reference to another type.

Parameters
  • tysyn – The fully-qualified name of the type synonym.

  • args – Type arguments (only applicable if the type is a generic type).

dazl.damlast.daml_types.var(a: str, *args: dazl.damlast.daml_lf_1.Type) dazl.damlast.daml_lf_1.Type

Construct a DAML Type that is equivalent to a (a type variable of the specified name).

DAML-LF fast lookups

class dazl.damlast.lookup.EmptyLookup(*args, **kwds)

A SymbolLookup that trivially throws for all of its functions.

This can be used where a SymbolLookup instance is useful but an implementation is not required.

All methods are implemented such that if the provided ref has a package ID, PackageNotFoundError is thrown; otherwise, NameNotFoundError is thrown.

archives() Collection[dazl.damlast.daml_lf_1.Archive]

Return the archives that are known to this lookup.

data_type(ref: Any) NoReturn

Return the DefDataType for the specified name.

data_type_name(ref: Any) NoReturn

Return the TypeConName that refers to a DefDataType that is known to exist in this lookup.

If this method succeeds, data_type() with the returned TypeConName as an argument should also always succeed.

package_ids() AbstractSet[PackageRef]

Return the package IDs that are known to this lookup.

template(ref: Any) NoReturn

Return the DefTemplate for the specified name.

template_name(ref: Any) NoReturn

Return the TypeConName that refers to a DefTemplate that is known to exist in this lookup.

If this method succeeds, data_type() with the returned TypeConName as an argument should also always succeed.

template_names(ref: Any) Collection[dazl.damlast.daml_lf_1.TypeConName]

Return all template names that are currently known that are a match for the query. Either PackageRef or the template name can be *.

Unlike the other methods of this class, this function should return an empty list in the case of a match failure; PackageNotFoundError or NameNotFoundError are never thrown.

value(ref: Any) NoReturn

Return the DefValue for the specified name.

class dazl.damlast.lookup.MultiPackageLookup(*args, **kwds)

Combines lookups across multiple archives.

This class is thread-safe. When calling add_archive() and any of the other read-only methods concurrently, read-only methods will NOT block; they will return the previous state of the lookup.

Packages can only be added; they cannot be removed once added.

add_archive(*a: dazl.damlast.daml_lf_1.Archive) None

Add one or more Archive instances to this lookup.

This method is thread-safe, but note that MultiPackageLookup allows dirty reads for performance reasons.

Parameters

a – One or more Archive instances to add.

archives() Collection[dazl.damlast.daml_lf_1.Archive]

Return the list of known archives.

data_type(ref: Any) dazl.damlast.daml_lf_1.DefDataType

Return the DefDataType for the specified name.

data_type_name(ref: Any) dazl.damlast.daml_lf_1.TypeConName

Return the TypeConName that refers to a DefDataType that is known to exist in this lookup.

If this method succeeds, data_type() with the returned TypeConName as an argument should also always succeed.

package_ids() AbstractSet[PackageRef]

Return the package IDs that are known to this lookup.

template(ref: Any) dazl.damlast.daml_lf_1.DefTemplate

Return the DefTemplate for the specified name.

template_name(ref: Any) dazl.damlast.daml_lf_1.TypeConName

Return the TypeConName that refers to a DefTemplate that is known to exist in this lookup.

If this method succeeds, data_type() with the returned TypeConName as an argument should also always succeed.

template_names(ref: Any) Collection[dazl.damlast.daml_lf_1.TypeConName]

Return all template names that are currently known that are a match for the query. Either PackageRef or the template name can be *.

Unlike the other methods of this class, this function should return an empty list in the case of a match failure; PackageNotFoundError or NameNotFoundError are never thrown.

value(ref: Any) dazl.damlast.daml_lf_1.DefValue

Return the DefValue for the specified name.

class dazl.damlast.lookup.PackageExceptionTracker(allow_deprecated_identifiers: bool = False)

A context manager that gracefully recovers from errors related to missing packages that are retryable.

pop_package() Optional[PackageRef]

Return a PackageRef that should be fetched before an operation is retried, or None if there is no such operation.

class dazl.damlast.lookup.PackageLookup(*args, **kwds)

Caching structure to make lookups on type names within a Package faster.

archives() Collection[dazl.damlast.daml_lf_1.Archive]

Return the archives that are known to this lookup.

data_type(ref: Any) dazl.damlast.daml_lf_1.DefDataType

Return the DefDataType for the specified name.

data_type_name(ref: Any) dazl.damlast.daml_lf_1.TypeConName

Return the TypeConName that refers to a DefDataType that is known to exist in this lookup.

If this method succeeds, data_type() with the returned TypeConName as an argument should also always succeed.

local_data_type(name: str) Optional[dazl.damlast.daml_lf_1.DefDataType]

Variation of data_type() that assumes the name is already scoped to this package. Unlike data_type(), this method returns None in the case of no match.

You should not normally use this method directly, and instead prefer to use the methods of the SymbolLookup protocol.

Parameters

name – A name to search for. Must be of the form "ModuleName:EntityName", where both modules and entities are dot-delimited.

Returns

Either a matching DefDataType, or None if no match.

local_template(name: str) Optional[dazl.damlast.daml_lf_1.DefTemplate]

Variation of data_type() that assumes the name is already scoped to this package. Unlike data_type(), this method returns None in the case of no match.

You should not normally use this method directly, and instead prefer to use the methods of the SymbolLookup protocol.

Parameters

name – A name to search for. Must be of the form "ModuleName:EntityName", where both modules and entities are dot-delimited.

Returns

Either a matching DefDataType, or None if no match.

local_value(name: str) Optional[dazl.damlast.daml_lf_1.DefValue]

Variation of data_type() that assumes the name is already scoped to this package. Unlike data_type(), this method returns None in the case of no match.

You should not normally use this method directly, and instead prefer to use the methods of the SymbolLookup protocol.

Parameters

name – A name to search for. Must be of the form "ModuleName:EntityName", where both modules and entities are dot-delimited.

Returns

Either a matching DefDataType, or None if no match.

package_ids() AbstractSet[PackageRef]

Return the package IDs that are known to this lookup.

template(ref: Any) dazl.damlast.daml_lf_1.DefTemplate

Return the DefTemplate for the specified name.

template_name(ref: Any) dazl.damlast.daml_lf_1.TypeConName

Return the TypeConName that refers to a DefTemplate that is known to exist in this lookup.

If this method succeeds, data_type() with the returned TypeConName as an argument should also always succeed.

template_names(ref: Any) Collection[dazl.damlast.daml_lf_1.TypeConName]

Return all template names that are currently known that are a match for the query. Either PackageRef or the template name can be *.

Unlike the other methods of this class, this function should return an empty list in the case of a match failure; PackageNotFoundError or NameNotFoundError are never thrown.

value(ref: Any) dazl.damlast.daml_lf_1.DefValue

Return the DefValue for the specified name.

dazl.damlast.lookup.find_choice(template: dazl.damlast.daml_lf_1.DefTemplate, name: str) dazl.damlast.daml_lf_1.TemplateChoice

Find a choice in a DefTemplate. If the choice could not be found, NameNotFoundError is raised.

dazl.damlast.lookup.matching_normalizations(__name: Union[str, dazl.damlast.daml_lf_1.TypeConName]) Sequence[str]

Return strings that are possible matches for the given template ID.

dazl.damlast.lookup.normalize(__name: Union[None, str, dazl.damlast.daml_lf_1.TypeConName]) str

Return the canonical form for a string that represents a template ID or partial match of a template ID.

Concretely, this function converts "MyMod:MyTemplate" to "*:MyMod:MyTemplate" and leaves most other strings unchanged.

Parameters

__name – A template ID, expressed in either string form or as an instance of TypeConName.

Returns

A string in canonical form (either PACKAGE_REF:MODULE_NAME:ENTITY_NAME or PACKAGE_REF:*, where PACKAGE_REF is also allowed to be *).

dazl.damlast.lookup.parse_type_con_name(val: str, allow_deprecated_identifiers: bool = False) dazl.damlast.daml_lf_1.TypeConName

Parse the given string as a type constructor.

dazl.damlast.lookup.validate_template(template: Any, allow_deprecated_identifiers: bool = False) Tuple[PackageRef, str]

Return a module and type name component from something that can be interpreted as a template.

Parameters
  • template – Any object that can be interpreted as an identifier for a template.

  • allow_deprecated_identifiers – Allow deprecated identifiers (UnresolvedTypeReference and a period delimiter instead of a colon between module names and entity names).

Returns

A tuple of package ID and Module.Name:EntityName (the package-scoped identifier for the type). The special value '*' is used if either the package ID, module name, or both should be wildcarded.

Raises

ValueError – If the object could not be interpreted as a thing referring to a template.

DAML-LF Archive parsing

Functions for creating Archive and Package instances.

parse_archive() can be used to take an arbitrary byte payload from the Package Service and convert it to an Archive; an Archive contains the package and its modules, which in turn contain templates, data types, and values.

dazl.damlast.parse.parse_archive(package_id: PackageRef, archive_bytes: bytes) dazl.damlast.daml_lf_1.Archive

Convert bytes into an Archive.

dazl.damlast.parse.parse_archive_payload(package_id: Optional[PackageRef], archive_bytes: bytes) com.daml.daml_lf_1_14.daml_lf_pb2.ArchivePayload

Convert bytes into a G.ArchivePayload.

Note that this function will temporarily increase Python’s recursion limit to handle cases where parsing a DAML-LF archive requires deeper recursion limits.

Error types

class dazl.damlast.errors.PackageNotFoundError(ref: daml_lf_1.PackageRef)

Raised when a Package was expected but could not be found.

This error can also be raised in places where types/values are being resolved; it is an indication that the operation MAY succeed if the package of the specified ID is fetched and the original option retried.

class dazl.damlast.errors.NameNotFoundError(ref: Any)

Raised when a daml_lf_1.DefDataType, daml_lf_1.DefValue, or daml_lf_1.DefTemplate of a specific name was expected, but could not be found.

Typically this error is raised when the package ID is valid, but the name is not. Because package IDs are immutable, this error is not normally retryable.