`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, **kwargs)¶

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.

interface(ref: Any) → NoReturn¶: Return the DefInterface for the specified name.

interface_name(ref: Any) → NoReturn¶: Return the TypeConName that refers to a DefInterface that is known to exist in this lookup.

package_ids() → AbstractSet[dazl.damlast.daml_lf_1.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(archives: Optional[Collection[dazl.damlast.daml_lf_1.Archive]] = None)¶

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.

interface(ref: Any) → dazl.damlast.daml_lf_1.DefInterface¶: Return the DefInterface for the specified name.

interface_name(ref: Any) → dazl.damlast.daml_lf_1.TypeConName¶: Return the TypeConName that refers to a DefInterface that is known to exist in this lookup.

package_ids() → AbstractSet[dazl.damlast.daml_lf_1.PackageRef]¶

Return the package IDs of packages stored in this lookup.

Because the data is local and in memory, the timeout parameter is ignored.

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[dazl.damlast.daml_lf_1.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(archive: dazl.damlast.daml_lf_1.Archive)¶

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.

interface(ref: Any) → dazl.damlast.daml_lf_1.DefInterface¶: Return the DefInterface for the specified name.

interface_name(ref: Any) → dazl.damlast.daml_lf_1.TypeConName¶: Return the TypeConName that refers to a DefInterface that is known to exist in this lookup.

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_interface(name: str) → Optional[dazl.damlast.daml_lf_1.DefInterface]¶

Variation of interface() that assumes the name is already scoped to this package. Unlike interface(), 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 DefInterface, or None if no match.

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

Variation of template() that assumes the name is already scoped to this package. Unlike template(), 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 DefTemplate, or None if no match.

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

Variation of value() that assumes the name is already scoped to this package. Unlike value(), 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 DefValue, or None if no match.

package_ids() → AbstractSet[dazl.damlast.daml_lf_1.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.SymbolLookup(*args, **kwargs)¶

Structural interface for a class that can synchronously provide type/value information.

If a requested _package_ could not be found, PackageNotFoundError is raised. If a requested package is known to this SymbolLookup but the name is unknown, then NameNotFoundError is raised. Callers can use this to disambiguate between errors that are retryable (missing packages can be fetched) and non-retryable (names within a known package, if they do not currently exist, will NEVER exist).

archives() → Collection[Archive]¶: Return the archives that are known to this lookup.

data_type(ref: Any) → DefDataType¶: Return the DefDataType for the specified name.

data_type_name(ref: Any) → 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.

interface(ref: Any) → DefInterface¶: Return the DefInterface for the specified name.

interface_name(ref: Any) → TypeConName¶: Return the TypeConName that refers to a DefInterface that is known to exist in this lookup.

package_ids() → AbstractSet[PackageRef]¶: Return the package IDs that are known to this lookup.

template(ref: Any) → DefTemplate¶: Return the DefTemplate for the specified name.

template_name(ref: Any) → 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[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) → 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[dazl.damlast.daml_lf_1.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: dazl.damlast.daml_lf_1.PackageRef, archive_bytes: bytes) → dazl.damlast.daml_lf_1.Archive¶: Convert bytes into an Archive.

dazl.damlast.parse.parse_archive_payload(package_id: Optional[dazl.damlast.daml_lf_1.PackageRef], archive_bytes: bytes) → com.daml.daml_lf_1_15.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.

dazl.damast¶

DAML-LF Archive types¶

DAML Types¶

DAML-LF fast lookups¶

DAML-LF Archive parsing¶

Error types¶

`dazl.damast`¶