`dazl.client`¶

Note

The types in this class are scheduled to be deprecated in dazl v8.0.0 in favor of the symbols in the dazl.ledger package.

They are not _currently_ deprecated, as some functionality still only exists in these types. For new projects, you are encouraged to use the types in dazl.ledger. See Migrate for more information on the changes and the motivation behind these changes.

Submodules¶

dazl.client.api module¶

This module contains the public API for interacting with the ledger from the perspective of a specific party.

class dazl.client.api.AIOGlobalClient(impl: dazl.client._network_client_impl._NetworkImpl)¶

Bases: dazl.client.api.GlobalClient

await ensure_dar(contents: Union[str, pathlib.Path, bytes, BinaryIO], timeout: Union[int, float, decimal.Decimal, str, datetime.timedelta] = 30) → None¶

Validate that the ledger has the packages specified by the given contents (as a byte array). Throw an exception if the specified DARs do not exist within the specified timeout.

Parameters

contents – The DAR or DALF to ensure.
timeout – The maximum length of time to wait before giving up.

await ensure_packages(package_ids: Collection[dazl.damlast.daml_lf_1.PackageRef], timeout: Union[int, float, decimal.Decimal, str, datetime.timedelta] = 30) → None¶

Validate that packages with the specified package IDs exist on the ledger. Throw an exception if the specified packages do not exist within the specified timeout.

Parameters

package_ids – The set of package IDs to check for.
timeout – The maximum length of time to wait before giving up.

await metadata() → dazl.client.ledger.LedgerMetadata¶: Return the current set of known packages.

class dazl.client.api.AIOPartyClient(impl: dazl.client._party_client_impl._PartyClientImpl)¶

Bases: dazl.client.api.PartyClient

Implementation of a PartyClient that exposes an async/await-style API that runs on an event loop.

add_ledger_archived(template: Any, handler: Callable[[dazl.protocols.events.ContractArchiveEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]], match: Union[None, Callable[[Mapping[str, Any]], bool], Mapping[str, Any]] = None) → None¶

Parameters

template – A template name to subscribe to, or ‘*’ to subscribe on all templates.
handler – The callback to invoke whenever a matching template is created.
match – An (optional) parameter that filters the templates to be received by the callback.

add_ledger_created(template: Any, handler: Callable[[dazl.protocols.events.ContractCreateEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]], match: Union[None, Callable[[Mapping[str, Any]], bool], Mapping[str, Any]] = None) → dazl.client.bots.Bot¶

Parameters

template – A template name to subscribe to, or ‘*’ to subscribe on all templates.
handler – The callback to invoke whenever a matching template is created.
match – An (optional) parameter that filters the templates to be received by the callback.

add_ledger_exercised(template: Any, choice: str, handler: Callable[[dazl.protocols.events.ContractExercisedEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]) → None¶

Parameters

template – A template name to subscribe to, or ‘*’ to subscribe on all templates.
choice – The name of the choice to listen for exercises on.
handler – The callback to invoke whenever a matching template is exercised.

add_ledger_init(handler: Callable[[dazl.protocols.events.InitEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]) → None¶

Register a callback to be invoked when the PartyClient has been instructed to begin, but before any network activity is started.

Parameters: handler – The handler to register. This can either be a coroutine or a normal function, and may return anything that can be successfully coerced into a CommandPayload.

add_ledger_packages_added(handler: Callable[[dazl.protocols.events.PackagesAddedEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]], initial: bool = False) → None¶

Parameters

handler – The handler to register. This can either be a coroutine or a normal function, and may return anything that can be successfully coerced into a CommandPayload.
initial – True to call the handler when the client is ready. This can be useful if you want to handle package additions identically whether they were already in the ledger when the client started up or only after a package has been added. The default value is False, which means that this handler is only called on NEW packages that have been uploaded after this client has started.

Returns

add_ledger_ready(handler: Callable[[dazl.protocols.events.ReadyEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]) → None¶

Register a callback to be invoked when the PartyClient has caught up to the head of the ledger, but before any ledger_create() or ledger_archive() callbacks are invoked.

Parameters: handler – The handler to register. This can either be a coroutine or a normal function, and may return anything that can be successfully coerced into a CommandPayload.

add_ledger_transaction_end(handler: Callable[[dazl.protocols.events.TransactionEndEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]) → None¶

Register a callback to be invoked when the PartyClient receives a new transaction. Called after individual ledger_create() and ledger_archive() callbacks.

Parameters: handler – The handler to register. This can either be a coroutine or a normal function, and may return anything that can be successfully coerced into a CommandPayload.

add_ledger_transaction_start(handler: Callable[[dazl.protocols.events.TransactionStartEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]) → None¶

Register a callback to be invoked when the PartyClient receives a new transaction. Called before individual ledger_create() and ledger_archive() callbacks.

Parameters: handler – The handler to register. This can either be a coroutine or a normal function, and may return anything that can be successfully coerced into a CommandPayload.

await create(_AIOPartyClient__template_id: Union[str, dazl.damlast.daml_lf_1.TypeConName], _AIOPartyClient__payload: Mapping[str, Any], *, workflow_id: Optional[str] = None, command_id: Optional[str] = None) → dazl.ledger.api_types.CreateEvent¶

Create a contract for a given template.

Parameters

__template_id –
The template of the contract to be created (positional argument only).

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__payload –
Template arguments for the contract to be created (positional argument only).

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
workflow_id – An optional workflow ID.
command_id – An optional command ID. If unspecified, a random one will be created.

Returns

The CreateEvent that represents the contract that was successfully created.

await create_and_exercise(_AIOPartyClient__template_id: Union[str, dazl.damlast.daml_lf_1.TypeConName], _AIOPartyClient__payload: Mapping[str, Any], _AIOPartyClient__choice_name: str, _AIOPartyClient__argument: Optional[Mapping[str, Any]] = None, *, workflow_id: Optional[str] = None, command_id: Optional[str] = None) → dazl.ledger.api_types.ExerciseResponse¶

Exercise a choice on a newly-created contract, in a single transaction.

Parameters

__template_id –
The template of the contract to be created (positional argument only).

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__payload –
Template arguments for the contract to be created (positional argument only).

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__choice_name –
The name of the choice to exercise (positional argument only).

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__argument –
The choice arguments. Can be omitted for choices that take no argument (positional argument only).

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
workflow_id – An optional workflow ID.
command_id – An optional command ID. If unspecified, a random one will be created.

Returns

The return value of the choice, together with a list of events that occurred as a result of exercising the choice.

await ensure_dar(contents: Union[str, pathlib.Path, bytes, BinaryIO], timeout: Union[int, float, decimal.Decimal, str, datetime.timedelta] = 30) → None¶

Validate that the ledger has the packages specified by the given contents (as a byte array). Throw an exception if the specified DARs do not exist within the specified timeout.

Parameters

contents – The DAR or DALF to ensure.
timeout – The maximum length of time to wait before giving up.

await exercise(_AIOPartyClient__contract_id: dazl.prim.contracts.ContractId, _AIOPartyClient__choice_name: str, _AIOPartyClient__argument: Optional[Mapping[str, Any]] = None, *, workflow_id: Optional[str] = None, command_id: Optional[str] = None) → dazl.ledger.api_types.ExerciseResponse¶

Exercise a choice on a contract identified by its contract ID.

Parameters

__contract_id –
The contract ID of the contract to exercise.

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__choice_name –
The name of the choice to exercise.

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__argument –
The choice arguments. Can be omitted for choices that take no argument.

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
workflow_id – An optional workflow ID.
command_id – An optional command ID. If unspecified, a random one will be created.

Returns

The return value of the choice, together with a list of events that occurred as a result of exercising the choice.

await exercise_by_key(_AIOPartyClient__template_id: Union[str, dazl.damlast.daml_lf_1.TypeConName], _AIOPartyClient__choice_name: str, _AIOPartyClient__key: Any, _AIOPartyClient__argument: Optional[Mapping[str, Any]] = None, *, workflow_id: Optional[str] = None, command_id: Optional[str] = None) → dazl.ledger.api_types.ExerciseResponse¶

Exercise a choice on a contract identified by its contract ID.

Parameters

__template_id –
The template of the contract to be created (positional argument only).

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__choice_name –
The name of the choice to exercise.

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__key –
The key of the contract to exercise.

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__argument –
The choice arguments. Can be omitted for choices that take no argument.

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
workflow_id – An optional workflow ID.
command_id – An optional command ID. If unspecified, a random one will be created.

Returns

The return value of the choice, together with a list of events that occurred as a result of exercising the choice.

find(template: Any, match: Union[None, Callable[[Mapping[str, Any]], bool], Mapping[str, Any]] = None, include_archived: bool = False) → dazl.client.state.ContractContextualDataCollection¶

find_active(template: Any, match: Union[None, Callable[[Mapping[str, Any]], bool], Mapping[str, Any]] = None) → Dict[dazl.prim.contracts.ContractId, Mapping[str, Any]]¶

Immediately return data from the current active contract set.

The contents of this ACS are guaranteed to be present (or removed) in the current transaction _before_ processing any corresponding on_created or on_archived callbacks for this party. The ACS is populated _before_ processing any on_ready callbacks.

This method raises an error if ACS tracking has been disabled on this client.

Parameters

template – The name of the template to fetch data from.
match – An optional dictionary whose keys are matched against corresponding field values.

Returns

A dict whose keys are ContractId and values are corresponding contract data that match the current query.

find_by_id(cid: Union[str, dazl.prim.contracts.ContractId]) → Optional[dazl.client.state.ContractContextualData]¶

find_historical(template: Any, match: Union[None, Callable[[Mapping[str, Any]], bool], Mapping[str, Any]] = None) → dazl.client.state.ContractContextualDataCollection¶

Immediately return data from the current active and historical contract set as a contextual data collection

The contents of this set are guaranteed to be up-to-date in the current transaction _before_ processing any corresponding on_created or on_archived callbacks for this party. The set is up-to-date _before_ processing any on_ready callbacks.

This method raises an error if historical tracking has been disabled on this client.

Parameters

template – The name of the template to fetch data from.
match – An optional dictionary whose keys are matched against corresponding field values.

Returns

A ContractContextualDataCollection whose values correspond to the contract data for active and archived contracts matching the current query.

find_nonempty(template: Any, match: Union[None, Callable[[Mapping[str, Any]], bool], Mapping[str, Any]], min_count: int = 1, timeout: float = 30) → Awaitable[Dict[dazl.prim.contracts.ContractId, Mapping[str, Any]]]¶

Return data from the current active contract set when at least some amount of rows exist in the active contract set.

Parameters

template – The name of the template to fetch data from.
match – An optional dictionary whose keys are matched against corresponding field values.
min_count – The minimum number of rows to return. The default value is 1.
timeout – Number of seconds in which to time out the search.

Returns

A Future that is resolved with a dict whose keys are ContractId and values are corresponding contract data that match the current query.

find_one(template: Any, match: Union[None, Callable[[Mapping[str, Any]], bool], Mapping[str, Any]] = None, timeout: float = 30) → Awaitable[Tuple[dazl.prim.contracts.ContractId, Mapping[str, Any]]]¶

Return data from the current active contract set when at least some amount of rows exist in the active contract set.

Parameters

template – The name of the template to fetch data from.
match – An optional dictionary whose keys are matched against corresponding field values.
timeout – Number of seconds in which to time out the search.

Returns

A Future that is resolved with a dict whose keys are ContractId and values are corresponding contract data that match the current query.

ledger_archived(template: Any, match: Union[None, Callable[[Mapping[str, Any]], bool], Mapping[str, Any]] = None) → Callable[[Callable[[dazl.protocols.events.ContractArchiveEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]], Callable[[dazl.protocols.events.ContractArchiveEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]]¶

Decorator for registering a callback to be invoked when the PartyClient encounters a newly archived contract instance of a template.

Parameters

template – A template name to subscribe to, or ‘*’ to subscribe on all templates.
match – An (optional) parameter that filters the templates to be received by the callback.

ledger_created(template: Any, match: Union[None, Callable[[Mapping[str, Any]], bool], Mapping[str, Any]] = None) → Callable[[Callable[[dazl.protocols.events.ContractCreateEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]], Callable[[dazl.protocols.events.ContractCreateEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]]¶

Parameters

template – A template name to subscribe to, or ‘*’ to subscribe on all templates.
match – An (optional) parameter that filters the templates to be received by the callback.

ledger_exercised(template: Any, choice: str) → Callable[[Callable[[dazl.protocols.events.ContractExercisedEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]], Callable[[dazl.protocols.events.ContractExercisedEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]]¶

Parameters

template – A template name to subscribe to, or ‘*’ to subscribe on all templates.
choice – The name of the choice to listen for exercises on.

ledger_init() → Callable[[Callable[[dazl.protocols.events.InitEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]], Callable[[dazl.protocols.events.InitEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]]¶: Decorator for registering a callback to be invoked when the PartyClient has been instructed to begin, but before any network activity is started.

ledger_packages_added(initial: bool = False) → Callable[[Callable[[dazl.protocols.events.PackagesAddedEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]], Callable[[dazl.protocols.events.PackagesAddedEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]]¶

Decorator for registering a callback to be invoked when the PartyClient has detected new packages added to the ledger.

Parameters: initial – True to call the handler when the client is ready. This can be useful if you want to handle package additions identically whether they were already in the ledger when the client started up or only after a package has been added. The default value is False, which means that this handler is only called on NEW packages that have been uploaded after this client has started.
Returns

ledger_ready() → Callable[[Callable[[dazl.protocols.events.ReadyEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]], Callable[[dazl.protocols.events.ReadyEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]]¶: Decorator for registering a callback to be invoked when the PartyClient has caught up to the head of the ledger, but before any ledger_create() or ledger_archive() callbacks are invoked.

ledger_transaction_end() → Callable[[Callable[[dazl.protocols.events.TransactionEndEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]], Callable[[dazl.protocols.events.TransactionEndEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]]¶: Decorator for registering a callback to be invoked when the PartyClient receives a new transaction. Called after individual ledger_create() and ledger_archive() callbacks.

ledger_transaction_start() → Callable[[Callable[[dazl.protocols.events.TransactionStartEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]], Callable[[dazl.protocols.events.TransactionStartEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload, Awaitable[Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]]]¶: Decorator for registering a callback to be invoked when the PartyClient receives a new transaction. Called before individual ledger_create() and ledger_archive() callbacks.

ready() → Awaitable[None]¶: Block until the ledger client has caught up to the current head and is ready to send commands.

set_config(url: Optional[str], **kwargs)¶

submit(commands: Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload], workflow_id: Optional[str] = None, deduplication_time: Optional[Union[int, float, decimal.Decimal, str, datetime.timedelta]] = None, *, command_id: Optional[str] = None) → Awaitable[None]¶

Submit commands to the ledger.

Parameters

commands – An object that can be converted to a command.
workflow_id – The optional workflow ID to stamp on the outgoing command.
deduplication_time – The length of the time window during which all commands with the same party and command ID will be deduplicated. Duplicate commands submitted before the end of this window return an ALREADY_EXISTS error.
command_id – An optional command ID. If unspecified, a random one will be created.

Returns

A future that resolves when the command has made it to the ledger _or_ an error occurred when trying to process them.

submit_create(template_name: Union[str, dazl.damlast.daml_lf_1.TypeConName, dazl.model.types.TypeReference, dazl.model.types.UnresolvedTypeReference, dazl.model.types.Template], arguments: Optional[dict] = None, workflow_id: Optional[str] = None, deduplication_time: Optional[Union[int, float, decimal.Decimal, str, datetime.timedelta]] = None) → Awaitable[None]¶

Submit a single create command. Equivalent to calling submit() with a single create.

Parameters

template_name – The name of the template.
arguments – The arguments to the create (as a dict).
workflow_id – The optional workflow ID to stamp on the outgoing command.
deduplication_time – The length of the time window during which all commands with the same party and command ID will be deduplicated. Duplicate commands submitted before the end of this window return an ALREADY_EXISTS error.

Returns

A future that resolves when the command has made it to the ledger _or_ an error occurred when trying to process them.

submit_create_and_exercise(template_name: Union[str, dazl.damlast.daml_lf_1.TypeConName, dazl.model.types.TypeReference, dazl.model.types.UnresolvedTypeReference, dazl.model.types.Template], arguments: dict, choice_name: str, choice_arguments: Optional[dict] = None, workflow_id: Optional[str] = None, deduplication_time: Optional[Union[int, float, decimal.Decimal, str, datetime.timedelta]] = None) → Awaitable[None]¶

Synchronously submit a single create-and-exercise command. Equivalent to calling submit() with a single create_and_exercise.

Parameters

template_name – The name of the template on which to do an exercise-by-key.
arguments – The arguments to the create (as a dict).
choice_name – The name of the choice to exercise.
choice_arguments – The arguments to the exercise (as a dict). Can be omitted (None) for no-argument
workflow_id – The optional workflow ID to stamp on the outgoing command.
deduplication_time – The length of the time window during which all commands with the same party and command ID will be deduplicated. Duplicate commands submitted before the end of this window return an ALREADY_EXISTS error.

submit_exercise(cid: dazl.prim.contracts.ContractId, choice_name: str, arguments: Optional[dict] = None, workflow_id: Optional[str] = None, deduplication_time: Optional[Union[int, float, decimal.Decimal, str, datetime.timedelta]] = None) → Awaitable[None]¶

Submit a single exercise choice. Equivalent to calling submit() with a single exercise.

Parameters

cid – The ContractId on which a choice is being exercised.
choice_name – The name of the choice to exercise.
arguments – The arguments to the exercise (as a dict). Can be omitted (None) for no-argument choices.
workflow_id – The optional workflow ID to stamp on the outgoing command.
deduplication_time – The length of the time window during which all commands with the same party and command ID will be deduplicated. Duplicate commands submitted before the end of this window return an ALREADY_EXISTS error.

Returns

A future that resolves when the command has made it to the ledger _or_ an error occurred when trying to process them.

submit_exercise_by_key(template_name: Union[str, dazl.damlast.daml_lf_1.TypeConName, dazl.model.types.TypeReference, dazl.model.types.UnresolvedTypeReference, dazl.model.types.Template], contract_key: Any, choice_name: str, arguments: Optional[dict] = None, workflow_id: Optional[str] = None, deduplication_time: Optional[Union[int, float, decimal.Decimal, str, datetime.timedelta]] = None) → Awaitable[None]¶

Synchronously submit a single exercise choice. Equivalent to calling submit() with a single exercise_by_key.

Parameters

template_name – The name of the template on which to do an exercise-by-key.
contract_key – The value that should uniquely identify a contract for the specified template.
choice_name – The name of the choice to exercise.
arguments – The arguments to the create (as a dict). Can be omitted (None) for no-argument choices.
workflow_id – The optional workflow ID to stamp on the outgoing command.
deduplication_time – The length of the time window during which all commands with the same party and command ID will be deduplicated. Duplicate commands submitted before the end of this window return an ALREADY_EXISTS error.

class dazl.client.api.GlobalClient(impl: dazl.client._network_client_impl._NetworkImpl)¶

Bases: object

Public interface for either an async-based or a thread-safe version of an API for interacting with a Ledger API implementation that manages global ledger data, such as package store management and current time.

class dazl.client.api.Network(metrics: Optional[dazl.metrics.api.MetricEvents] = None)¶

Bases: object

Manages network connection/scheduling logic on behalf of one or more PartyClient instances.

aio_global() → dazl.client.api.AIOGlobalClient¶

Return a GlobalClient that works on an asyncio event loop.

Note that once this object can only be accessed from the asyncio event loop it is intended to be used on.

aio_new_party() → dazl.client.api.AIOPartyClient¶: Return a PartyClient for a random party that works on an asyncio event loop. This will never return the same object twice.

aio_party(party: Union[str, dazl.prim.party.Party]) → dazl.client.api.AIOPartyClient¶

Return a PartyClient that works on an asyncio event loop.

Parameters: party – The party to get a client for.

await aio_run(*coroutines, keep_open: bool = True) → None¶

Coroutine where all network activity is scheduled from. This coroutine exits when shutdown() is called, and can be used directly as an asyncio-native alternative to start_in_background() and join().

You would normally call this method directly only if you are trying to incorporate the client into an already-running event loop. Prefer run_until_complete() or run_forever() if you can block the current thread, or start_in_background() with join() if you wish to run the entire client on background threads.

bots() → Collection[dazl.client.bots.Bot]¶

Return a collection of bots.

Note that bot introspection will not be a part of the dazl v8 API.

join(timeout: Optional[float] = None) → None¶

Block the current thread until the client is shut down.

Parameters: timeout – Number of seconds to wait before timing out the join, or None to wait indefinitely.

property lookup: dazl.damlast.protocols.SymbolLookup¶: Return a SymbolLookup that provides type and package information for known packages.

parties() → Collection[dazl.prim.party.Party]¶: Return a snapshot of the set of parties that exist right now.

party_bots(party: Union[str, dazl.prim.party.Party], if_missing: Literal[1, 2, 3] = 1) → dazl.client.bots.BotCollection¶

Return the collection of bots associated with a party.

Parameters

party – The party to get bots for.
if_missing – Specify the behavior to use in the case where no client has been yet requested for this party. The default behavior is CREATE_IF_MISSING.

resolved_config() → dazl.client.config.NetworkConfig¶: Calculate the configuration that will be used for this client when it is instantiated.

run_forever(*coroutines: Awaitable[None], install_signal_handlers: Optional[bool] = None) → None¶: Block the main thread and run the application in an event loop on the main thread. The loop terminates when shutdown() is called AND all active command submissions and event handlers’ follow-ups have successfully returned.

run_until_complete(*coroutines: Awaitable[None], install_signal_handlers: Optional[bool] = None) → None¶

Block the main thread and run the application in an event loop on the main thread. The loop terminates when the given (optional) coroutines terminate OR shutdown() is called AND all active command submissions and event handlers’ follow-ups have successfully returned.

Parameters

coroutines – Coroutines to run alongside event handlers and command submissions. When these coroutines are done running and the
install_signal_handlers – True to install SIGINT and SIGQUIT event handlers (CTRL+C and CTRL+); False to skip installation. The default value is None, which installs signal handlers only when called from the main thread (default). If signal handlers are requested to be installed and the thread is NOT the main thread, this method throws.

set_config(*config: Union[dazl.client.config.NetworkConfig, dazl.client.config.AnonymousNetworkConfig], url: Optional[str] = None, admin_url: Optional[str] = None, **kwargs)¶

shutdown() → Optional[Awaitable[None]]¶

Gracefully shut down all network connections and notify all clients that they are about to be terminated.

The current thread does NOT block.

Returns: None unless start() was called, in which case the coroutine that corresponds to dazl’s “main” is returned.

simple_global() → dazl.client.api.SimpleGlobalClient¶: Return a GlobalClient that exposes thread-safe, synchronous (blocking) methods for communicating with a ledger. Callbacks are dispatched to background threads.

simple_new_party() → dazl.client.api.SimplePartyClient¶: Return a PartyClient that exposes thread-safe, synchronous (blocking) methods for communicating with a ledger. Callbacks are dispatched to background threads.

simple_party(party: Union[str, dazl.prim.party.Party]) → dazl.client.api.SimplePartyClient¶

Return a PartyClient that exposes thread-safe, synchronous (blocking) methods for communicating with a ledger. Callbacks are dispatched to background threads.

Parameters: party – The party to get a client for.

start() → None¶: Start the coroutine that spawns callbacks for listeners on event streams.

start_in_background(daemon: bool = True, install_signal_handlers: Optional[bool] = None) → None¶

Connect to the ledger in a background thread.

The current thread does NOT block. Operations on instances of SimplePartyClient are allowed, and operations on instances of AIOPartyClient are allowed as long as they are made from the correct thread.

class dazl.client.api.PartyClient(impl: dazl.client._party_client_impl._PartyClientImpl)¶

Bases: object

Public interface for either an async-based or a thread-safe version of an API for interacting with a Ledger API implementation from the perspective of a single client.

property party: dazl.prim.party.Party¶: Return the party serviced by this client.

resolved_config() → dazl.client.config.PartyConfig¶: Calculate the configuration that will be used for this client when it is instantiated.

class dazl.client.api.SimpleGlobalClient(impl: dazl.client._network_client_impl._NetworkImpl)¶

Bases: dazl.client.api.GlobalClient

ensure_dar(contents: Union[str, pathlib.Path, bytes, BinaryIO], timeout: Union[int, float, decimal.Decimal, str, datetime.timedelta] = 30) → None¶

Validate that the ledger has the packages specified by the given contents (as a byte array). Throw an exception if the specified DARs do not exist within the specified timeout.

Parameters

contents – The DAR or DALF to ensure.
timeout – The maximum length of time to wait before giving up.

ensure_packages(package_ids: Collection[dazl.damlast.daml_lf_1.PackageRef], timeout: Union[int, float, decimal.Decimal, str, datetime.timedelta] = 30) → None¶

Validate that packages with the specified package IDs exist on the ledger. Throw an exception if the specified packages do not exist within the specified timeout.

Parameters

package_ids – The set of package IDs to check for.
timeout – The maximum length of time to wait before giving up.

metadata(timeout: Union[int, float, decimal.Decimal, str, datetime.timedelta] = 30) → dazl.client.ledger.LedgerMetadata¶: Return the current set of known packages.

class dazl.client.api.SimplePartyClient(impl: dazl.client._party_client_impl._PartyClientImpl)¶

Bases: dazl.client.api.PartyClient

Implementation of a PartyClient that exposes blocking calls, but can be used from any thread.

Use this implementation if any of these apply:

you wish to interact with libraries that do not natively support asyncio
you are comfortable with the trade-off of having to block threads in order to write code

Parameters

template – A template name to subscribe to, or ‘*’ to subscribe on all templates.
handler – The callback to invoke whenever a matching template is created.
match – An (optional) parameter that filters the templates to be received by the callback.

Parameters

template – A template name to subscribe to, or ‘*’ to subscribe on all templates.
handler – The callback to invoke whenever a matching template is created.
match – An (optional) parameter that filters the templates to be received by the callback.

Parameters

template – A template name to subscribe to, or ‘*’ to subscribe on all templates.
choice – The name of the choice to listen for exercises on.
handler – The callback to invoke whenever a matching template is exercised.

Register a callback to be invoked when the PartyClient has been instructed to begin, but before any network activity is started.

Parameters: handler – The handler to register. May return anything that can be successfully coerced into a CommandPayload.

Parameters

handler – The handler to register. May return anything that can be successfully coerced into a CommandPayload.
initial – True to call the handler when the client is ready. This can be useful if you want to handle package additions identically whether they were already in the ledger when the client started up or only after a package has been added. The default value is False, which means that this handler is only called on NEW packages that have been uploaded after this client has started.

Returns

Register a callback to be invoked when the PartyClient has caught up to the head of the ledger, but before any ledger_create() or ledger_archive() callbacks are invoked.

Parameters: handler – The handler to register. May return anything that can be successfully coerced into a CommandPayload.

Register a callback to be invoked when the PartyClient receives a new transaction. Called after individual ledger_create() and ledger_archive() callbacks.

Parameters: handler – The handler to register. This can either be a coroutine or a normal function, and may return anything that can be successfully coerced into a CommandPayload.

Register a callback to be invoked when the PartyClient receives a new transaction. Called before individual ledger_create() and ledger_archive() callbacks.

Parameters: handler – The handler to register. This can either be a coroutine or a normal function, and may return anything that can be successfully coerced into a CommandPayload.

create(_SimplePartyClient__template_id: Union[str, dazl.damlast.daml_lf_1.TypeConName], _SimplePartyClient__payload: Mapping[str, Any], *, workflow_id: Optional[str] = None, command_id: Optional[str] = None) → dazl.ledger.api_types.CreateEvent¶

Create a contract for a given template.

Parameters

__template_id –
The template of the contract to be created (positional argument only).

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__payload –
Template arguments for the contract to be created (positional argument only).

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
workflow_id – An optional workflow ID.
command_id – An optional command ID. If unspecified, a random one will be created.

Returns

The CreateEvent that represents the contract that was successfully created.

create_and_exercise(_SimplePartyClient__template_id: Union[str, dazl.damlast.daml_lf_1.TypeConName], _SimplePartyClient__payload: Mapping[str, Any], _SimplePartyClient__choice_name: str, _SimplePartyClient__argument: Optional[Mapping[str, Any]] = None, *, workflow_id: Optional[str] = None, command_id: Optional[str] = None) → dazl.ledger.api_types.ExerciseResponse¶

Exercise a choice on a newly-created contract, in a single transaction.

Parameters

__template_id –
The template of the contract to be created (positional argument only).

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__payload –
Template arguments for the contract to be created (positional argument only).

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__choice_name –
The name of the choice to exercise (positional argument only).

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__argument –
The choice arguments. Can be omitted for choices that take no argument (positional argument only).

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
workflow_id – An optional workflow ID.
command_id – An optional command ID. If unspecified, a random one will be created.

Returns

The return value of the choice, together with a list of events that occurred as a result of exercising the choice.

ensure_dar(contents: Union[str, pathlib.Path, bytes, BinaryIO], timeout: Union[int, float, decimal.Decimal, str, datetime.timedelta] = 30) → None¶

Validate that the ledger has the packages specified by the given contents (as a byte array). Throw an exception if the specified DARs do not exist within the specified timeout.

Parameters

contents – The DAR or DALF to ensure.
timeout – The maximum length of time to wait before giving up.

exercise(_SimplePartyClient__contract_id: dazl.prim.contracts.ContractId, _SimplePartyClient__choice_name: str, _SimplePartyClient__argument: Optional[Mapping[str, Any]] = None, *, workflow_id: Optional[str] = None, command_id: Optional[str] = None) → dazl.ledger.api_types.ExerciseResponse¶

Exercise a choice on a contract identified by its contract ID.

Parameters

__contract_id –
The contract ID of the contract to exercise.

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__choice_name –
The name of the choice to exercise.

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__argument –
The choice arguments. Can be omitted for choices that take no argument.

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
workflow_id – An optional workflow ID.
command_id – An optional command ID. If unspecified, a random one will be created.

Returns

The return value of the choice, together with a list of events that occurred as a result of exercising the choice.

exercise_by_key(_SimplePartyClient__template_id: Union[str, dazl.damlast.daml_lf_1.TypeConName], _SimplePartyClient__choice_name: str, _SimplePartyClient__key: Any, _SimplePartyClient__argument: Optional[Mapping[str, Any]] = None, *, workflow_id: Optional[str] = None, command_id: Optional[str] = None) → dazl.ledger.api_types.ExerciseResponse¶

Exercise a choice on a contract identified by its contract ID.

Parameters

__template_id –
The template of the contract to be created (positional argument only).

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__choice_name –
The name of the choice to exercise.

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__key –
The key of the contract to exercise.

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
__argument –
The choice arguments. Can be omitted for choices that take no argument.

Note that future versions reserve the right to rename this parameter name at any time; it should be passed in as a positional parameter and never by name.
workflow_id – An optional workflow ID.
command_id – An optional command ID. If unspecified, a random one will be created.

Returns

The return value of the choice, together with a list of events that occurred as a result of exercising the choice.

find(template: Any, match: Union[None, Callable[[Mapping[str, Any]], bool], Mapping[str, Any]] = None, include_archived: bool = False) → dazl.client.state.ContractContextualDataCollection¶

find_active(template: Any, match: Union[None, Callable[[Mapping[str, Any]], bool], Mapping[str, Any]] = None) → Dict[dazl.prim.contracts.ContractId, Mapping[str, Any]]¶

Immediately return data from the current active contract set.

This method raises an error if ACS tracking has been disabled on this client.

Parameters

template – The name of the template to fetch data from.
match – An optional dictionary whose keys are matched against corresponding field values.

Returns

A dict whose keys are ContractId and values are corresponding contract data that match the current query.

Returns

A dict whose keys are ContractId and values are corresponding contract data that match the current query.

find_by_id(cid: Union[str, dazl.prim.contracts.ContractId]) → Optional[dazl.client.state.ContractContextualData]¶

find_historical(template: Any, match: Union[None, Callable[[Mapping[str, Any]], bool], Mapping[str, Any]] = None) → dazl.client.state.ContractContextualDataCollection¶

Immediately return data from the current active and historical contract set.

This method raises an error if historical tracking has been disabled on this client.

Parameters

template – The name of the template to fetch data from.
match – An optional dictionary whose keys are matched against corresponding field values.

Returns

A dict whose keys are ContractId and values are corresponding contract data that match the current query.

Returns

A dict whose keys are ContractId and values are corresponding contract data that match the current query.

find_nonempty(template: Any, match: Union[None, Callable[[Mapping[str, Any]], bool], Mapping[str, Any]], min_count: int = 1, timeout: float = 30) → Dict[dazl.prim.contracts.ContractId, Mapping[str, Any]]¶

Return data from the current active contract set when at least some amount of rows exist in the active contract set.

Parameters

template – The name of the template to fetch data from.
match – An optional dictionary whose keys are matched against corresponding field values.
min_count – The minimum number of rows to return. The default value is 1.
timeout – Number of seconds in which to time out the search.

Returns

A Future that is resolved with a dict whose keys are ContractId and values are corresponding contract data that match the current query.

find_one(template: Any, match: Union[None, Callable[[Mapping[str, Any]], bool], Mapping[str, Any]] = None, timeout: float = 30) → Tuple[dazl.prim.contracts.ContractId, Mapping[str, Any]]¶

Return data from the current active contract set when at least some amount of rows exist in the active contract set.

Parameters

template – The name of the template to fetch data from.
match – An optional dictionary whose keys are matched against corresponding field values.
timeout – Number of seconds in which to time out the search.

Returns

A Future that is resolved with a dict whose keys are ContractId and values are corresponding contract data that match the current query.

Decorator for registering a callback to be invoked when the PartyClient encounters a newly archived contract instance of a template.

Parameters

template – A template name to subscribe to, or ‘*’ to subscribe on all templates.
match – An (optional) parameter that filters the templates to be received by the callback.

Parameters

template – A template name to subscribe to, or ‘*’ to subscribe on all templates.
match – An (optional) parameter that filters the templates to be received by the callback.

Parameters

template – A template name to subscribe to, or ‘*’ to subscribe on all templates.
choice – The name of the choice to listen for exercises on.

ledger_init() → Callable[[Callable[[dazl.protocols.events.InitEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]], Callable[[dazl.protocols.events.InitEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]¶: Decorator for registering a callback to be invoked when the PartyClient has been instructed to begin, but before any network activity is started.

Decorator for registering a callback to be invoked when the PartyClient has detected new packages added to the ledger.

Parameters: initial – True to call the handler when the client is ready. This can be useful if you want to handle package additions identically whether they were already in the ledger when the client started up or only after a package has been added. The default value is False, which means that this handler is only called on NEW packages that have been uploaded after this client has started.
Returns

ledger_ready() → Callable[[Callable[[dazl.protocols.events.ReadyEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]], Callable[[dazl.protocols.events.ReadyEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]¶: Decorator for registering a callback to be invoked when the PartyClient has caught up to the head of the ledger, but before any ledger_create() or ledger_archive() callbacks are invoked.

ledger_transaction_end() → Callable[[Callable[[dazl.protocols.events.TransactionEndEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]], Callable[[dazl.protocols.events.TransactionEndEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]¶: Decorator for registering a callback to be invoked when the PartyClient receives a new transaction. Called after individual ledger_create() and ledger_archive() callbacks.

ledger_transaction_start() → Callable[[Callable[[dazl.protocols.events.TransactionStartEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]], Callable[[dazl.protocols.events.TransactionStartEvent], Union[None, dazl.ledger.api_types.Command, Sequence[Optional[dazl.ledger.api_types.Command]], dazl.client.commands.CommandBuilder, dazl.client.commands.CommandPayload]]]¶: Decorator for registering a callback to be invoked when the PartyClient receives a new transaction. Called before individual ledger_create() and ledger_archive() callbacks.

ready() → None¶: Block until the underlying infrastructure has connected to all necessary services.

set_config(url: Optional[str], **kwargs)¶

submit(commands, workflow_id: Optional[str] = None, deduplication_time: Optional[Union[int, float, decimal.Decimal, str, datetime.timedelta]] = None) → None¶

Submit commands to the ledger.

Parameters

commands – An object that can be converted to a command.
workflow_id – The optional workflow ID to stamp on the outgoing command.
deduplication_time – The length of the time window during which all commands with the same party and command ID will be deduplicated. Duplicate commands submitted before the end of this window return an ALREADY_EXISTS error.

Returns

A future that resolves when the command has made it to the ledger _or_ an error occurred when trying to process them.

Synchronously submit a single create command. Equivalent to calling submit() with a single create.

Parameters

template_name – The name of the template.
arguments – The arguments to the create (as a dict).
workflow_id – The optional workflow ID to stamp on the outgoing command.
deduplication_time – The length of the time window during which all commands with the same party and command ID will be deduplicated. Duplicate commands submitted before the end of this window return an ALREADY_EXISTS error.

Synchronously submit a single create-and-exercise command. Equivalent to calling submit() with a single create_and_exercise.

Parameters

template_name – The name of the template on which to do an exercise-by-key.
arguments – The arguments to the create (as a dict).
choice_name – The name of the choice to exercise.
choice_arguments – The arguments to the exercise (as a dict). Can be omitted (None) for no-argument
workflow_id – The optional workflow ID to stamp on the outgoing command.
deduplication_time – The length of the time window during which all commands with the same party and command ID will be deduplicated. Duplicate commands submitted before the end of this window return an ALREADY_EXISTS error.

Synchronously submit a single exercise choice. Equivalent to calling submit() with a single exercise.

Parameters

cid – The ContractId on which a choice is being exercised.
choice_name – The name of the choice to exercise.
arguments – The arguments to the exercise (as a dict). Can be omitted (None) for no-argument choices.
workflow_id – The optional workflow ID to stamp on the outgoing command.
deduplication_time – The length of the time window during which all commands with the same party and command ID will be deduplicated. Duplicate commands submitted before the end of this window return an ALREADY_EXISTS error.

Synchronously submit a single exercise choice. Equivalent to calling submit() with a single exercise_by_key.

Parameters

template_name – The name of the template on which to do an exercise-by-key.
contract_key – The value that should uniquely identify a contract for the specified template.
choice_name – The name of the choice to exercise.
arguments – The arguments to the create (as a dict). Can be omitted (None) for no-argument choices.
workflow_id – The optional workflow ID to stamp on the outgoing command.
deduplication_time – The length of the time window during which all commands with the same party and command ID will be deduplicated. Duplicate commands submitted before the end of this window return an ALREADY_EXISTS error.

class dazl.client.api.async_network(url: Optional[str] = None, dars: Optional[Union[bytes, str, pathlib.Path, BinaryIO, Collection[Union[bytes, str, pathlib.Path, BinaryIO]]]] = None)¶

Bases: object

Create a Network and ensure that it has the given set of DARs loaded.

with dazl.client.api.simple_client(url: Optional[str] = None, party: Union[None, str, dazl.prim.party.Party] = None, log_level: Optional[int] = 20)¶

Start up a single client connecting to a single specific party.

Parameters

url – The URL of the client to connect to. Defaults to the value of the DAML_LEDGER_URL environment variable (if set).
party – The party to connect as. Defaults to the value of the DAML_LEDGER_PARTY environment variable if it is set.
log_level – If non-None, configure a default logger that logs output at the specified level. The default value is INFO.

Returns

A SimplePartyClient that can be used in a completely blocking, synchronous fashion.

dazl.client.bots module¶

class dazl.client.bots.Bot(party_client: Optional[PartyClient], name: str)¶

Bases: object

add_event_handler(keys: Union[str, Collection[str]], handler: Callable[[dazl.client.bots.E], Any], filter_fn: Optional[Callable[[dazl.client.bots.E], bool]] = None) → None¶

Add a new event handler to this bot for the specified event.

Parameters

keys – The key(s) of the event (as returned by EventKey.from_event()).
filter_fn – An optional callback that returns True or False on whether the corresponding callback should be invoked. This cannot be a coroutine function.
handler – An event handler to be invoked when an event with the specified key is raised.

entries() → Sequence[dazl.client.bots.BotEntry]¶: The collection of individual event handlers in a bot, in the order that they will be executed.

event_keys() → AbstractSet[str]¶: Return the set of keys that event handlers in this bot are configured to handle.

property id: str¶: The ID of this bot, generated at runtime.

ledger_created(template: Any)¶

property name¶: The name of this bot. Defaults to the name of the original event handler if unspecified.

notify(event: dazl.protocols.events.BaseEvent) → Awaitable[None]¶

Notifies handler(s) associated with this bot that the given event has occurred. Note that this notification is asynchronous: in other words, event handlers will not have processed this event by the time this function returns.

Parameters: event – The event to raise.

property party: Optional[dazl.prim.party.Party]¶: Primary party that this bot receives events for (and potentially generates commands for).

pause() → None¶: Immediately change the state of this bot to PAUSING, and pause event handler invocations. The event handler currently running is allowed to complete. When that is completed, the state is changed to PAUSED.

resume() → None¶: Immediately change the state of this bot to RESUMING and process any events that have queued up while the bot was paused. When this queue is fully drained, the state is changed to RUNNING.

property running: bool¶: Return True if this bot is currently processing events.

property state: dazl.client.bots.BotState¶: Current running state of the bot.

stop()¶: Permanently stop this bot. If you need to be able to “restart” a stopped bot, use pause() and resume() instead.

wants_any_keys(keys: Collection[str]) → bool¶

class dazl.client.bots.BotCollection(party: Optional[dazl.prim.party.Party])¶

Bases: Sequence[dazl.client.bots.Bot]

A collection of bots for a party.

This class is thread-safe except for notify() and _main() in order to support adding event handlers from any thread. The most common use of this is for SimplePartyClient instances, where event registration is done from the main thread (from the perspective of the caller) and event notifications are done on an asyncio event loop thread (hidden from the caller).

add_new(name: str, party_client: Optional[PartyClient] = None) → Bot¶

add_single(keys: Union[str, Sequence[str]], handler: BotCallback, filter_fn: Optional[BotFilter] = None, name: Optional[str] = None, party_client: Optional[PartyClient] = None) → Bot¶: Convenience method for creating a bot with a single event handler.

notify(event: dazl.protocols.events.BaseEvent)¶

stop_all()¶

class dazl.client.bots.BotEntry(event_key: str, callback: Callable[[E], Any], filter: Optional[Callable[[E], bool]] = None, source_location: Optional[dazl.client.bots.SourceLocation] = None)¶

Bases: object

callback: Callable[[dazl.client.bots.E], Any]¶

event_key: str¶

filter: Optional[Callable[[dazl.client.bots.E], bool]] = None¶

source_location: Optional[dazl.client.bots.SourceLocation] = None¶

class dazl.client.bots.BotInvocation(event: dazl.protocols.events.BaseEvent, future: _asyncio.Future = <factory>)¶

Bases: object

event: dazl.protocols.events.BaseEvent¶

future: _asyncio.Future¶

class dazl.client.bots.BotState(value)¶

Bases: enum.Enum

Possible states of a Bot.

PAUSED = 'PAUSED'¶

PAUSING = 'PAUSING'¶: This bot has been told to pause, but has not yet completed processing events in flight.

RESUMING = 'RESUMING'¶

RUNNING = 'RUNNING'¶

STARTING = 'STARTING'¶: The bot is starting (has not yet received the “ready” event).

STOPPED = 'STOPPED'¶

STOPPING = 'STOPPING'¶

class dazl.client.bots.SourceLocation(file_name: Optional[str], start_line: int, end_line: int)¶

Bases: object

end_line: int¶

file_name: Optional[str]¶

start_line: int¶

dazl.client.bots.wrap_as_command_submission(submit_fn, callback, filter) → Callable[[dazl.protocols.events.BaseEvent], Awaitable[Any]]¶: Normalize a callback to something that takes a single contract ID and contract data, and return an awaitable that is resolved when the underlying command has been fully submitted.

Module contents¶

`dazl.client` package¶

The dazl.client module a high-level view of the Ledger API in a friendly way.

It provides:

a callback-based API for interacting with events on the read-side of the Ledger API

convenient methods for creating arbitrary commands on the write-side of the Ledger API.

For a higher-level, more declarative API, see dazl.query.

dazl.client¶

Submodules¶

dazl.client.api module¶

dazl.client.bots module¶

Module contents¶

dazl.client package¶

`dazl.client`¶

`dazl.client` package¶