dazl

dazl package

This module contains the Python API for interacting with the Ledger API.

class dazl.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], match: Union[None, Callable[Mapping[str, Any], bool], Mapping[str, Any]] = None) None

Register 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.

  • 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], match: Union[None, Callable[Mapping[str, Any], bool], Mapping[str, Any]] = None) dazl.client.bots.Bot

Register a callback to be invoked when the PartyClient encounters a newly created contract instance of a template.

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]) None

Register a callback to be invoked when the PartyClient encounters an exercised choice event.

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]) 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], initial: bool = False) None

Register a callback to be invoked when the PartyClient has detected new packages added to the ledger.

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.

  • initialTrue 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]) 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]) 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]) 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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[dazl.protocols.events.ContractArchiveEvent]

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[dazl.protocols.events.ContractCreateEvent]

Register a callback to be invoked when the PartyClient encounters a newly created 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_exercised(template: Any, choice: str) Callable[dazl.protocols.events.ContractExercisedEvent]

Register a callback to be invoked when the PartyClient encounters an exercised choice event.

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[dazl.protocols.events.InitEvent]

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[dazl.protocols.events.PackagesAddedEvent]

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

Parameters

initialTrue 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[dazl.protocols.events.ReadyEvent]

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[dazl.protocols.events.TransactionEndEvent]

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[dazl.protocols.events.TransactionStartEvent]

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.Command

Bases: object

Base class for write-side commands.

This class provides no functionality on its own.

dazl.ContractData

alias of Mapping[str, Any]

class dazl.ContractId(contract_id: str, template_id: Union[str, Type, TypeConName])

Bases: dazl.prim.contracts.ContractId

property contract_id: str

Get the raw contract ID value (for example, "#4:1").

exercise(choice_name, arguments=None)

Create an ExerciseCommand that represents the result of exercising a choice on this contract with the specified choice.

Parameters
  • choice_name – The name of the choice to exercise.

  • arguments – (optional) A dict of named values to send as parameters to the choice exercise.

for_json()

Return the JSON representation of this contract. This is currently just the contract ID string itself.

replace(contract_id=None, template_id=None)

Return a new ContractId instance replacing specified fields with values.

property template_id: TypeReference

Get the type of template that is pointed to by this ContractId as a TypeReference. Note that usage of Type and TypeReference are deprecated, and value_type() should be used instead.

As of dazl 7.3.0, the TemplateId is always normalized to a TypeReference, regardless of what the ContractId was constructed with.

class dazl.CreateAndExerciseCommand(template: Union[str, dazl.damlast.daml_lf_1.TypeConName], arguments: Mapping[str, Any], choice: str, choice_argument: Optional[Any] = None)

Bases: dazl.ledger.api_types.CreateAndExerciseCommand

A command that exercises a choice on a newly-created contract, in a single transaction.

property arguments: Any

Use payload() instead.

property choice_argument: Any

Use argument() instead.

property template_type: dazl.damlast.daml_lf_1.TypeConName

Use template_id() instead.

class dazl.CreateCommand(template: Union[str, dazl.damlast.daml_lf_1.TypeConName], arguments: Optional[Mapping[str, Any]] = None)

Bases: dazl.ledger.api_types.CreateCommand

A command that creates a contract without any predecessors.

property arguments: Mapping[str, Any]

Use payload() instead.

property template_type: dazl.damlast.daml_lf_1.TypeConName

Use template_id() instead.

exception dazl.DazlError

Bases: Exception

Superclass of errors raised by dazl.

class dazl.ExerciseByKeyCommand(template: Union[str, dazl.damlast.daml_lf_1.TypeConName], contract_key: Any, choice: str, choice_argument: Optional[Any] = None)

Bases: dazl.ledger.api_types.ExerciseByKeyCommand

property choice_argument: Any

Use argument() instead.

property contract_key: Any

Use argument() instead.

property template_type: dazl.damlast.daml_lf_1.TypeConName

Use template_id() instead.

class dazl.ExerciseCommand(contract: dazl.prim.contracts.ContractId, choice: str, arguments: Optional[Any] = None)

Bases: dazl.ledger.api_types.ExerciseCommand

A command that exercises a choice on a contract identified by its contract ID.

property arguments: Any

Use argument() instead.

property contract: dazl.prim.contracts.ContractId

Use contract_id() instead.

class dazl.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, 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[Party]

Return a snapshot of the set of parties that exist right now.

party_bots(party: Union[str, Party], if_missing: typing_extensions.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_handlersTrue 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, 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.

dazl.Party(x)
class dazl.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

add_ledger_archived(template: Any, handler: Callable[dazl.protocols.events.ContractArchiveEvent], match: Union[None, Callable[Mapping[str, Any], bool], Mapping[str, Any]] = None) None

Register 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.

  • 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], match: Union[None, Callable[Mapping[str, Any], bool], Mapping[str, Any]] = None) None

Register a callback to be invoked when the PartyClient encounters a newly created contract instance of a template.

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]) None

Register a callback to be invoked when the PartyClient encounters an exercised choice event.

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]) 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. May return anything that can be successfully coerced into a CommandPayload.

add_ledger_packages_added(handler: Callable[dazl.protocols.events.PackagesAddedEvent], initial: bool = False) None

Register a callback to be invoked when the PartyClient has detected new packages added to the ledger.

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

  • initialTrue 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]) 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. May return anything that can be successfully coerced into a CommandPayload.

add_ledger_transaction_end(handler: Callable[dazl.protocols.events.TransactionEndEvent]) 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]) 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.

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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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 of dazl 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.

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.

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 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.

ledger_archived(template: Any, match: Union[None, Callable[Mapping[str, Any], bool], Mapping[str, Any]] = None) Callable[dazl.protocols.events.ContractArchiveEvent]

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[dazl.protocols.events.ContractCreateEvent]

Register a callback to be invoked when the PartyClient encounters a newly created 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_exercised(template: Any, choice: str) Callable[dazl.protocols.events.ContractExercisedEvent]

Register a callback to be invoked when the PartyClient encounters an exercised choice event.

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[dazl.protocols.events.InitEvent]

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[dazl.protocols.events.PackagesAddedEvent]

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

Parameters

initialTrue 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[dazl.protocols.events.ReadyEvent]

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[dazl.protocols.events.TransactionEndEvent]

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[dazl.protocols.events.TransactionStartEvent]

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.

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) None

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.

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) 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) None

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.

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) 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.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.

dazl.connect(**kwargs)

Connect to a gRPC Ledger API implementation and return a connection that uses asyncio.

dazl.create(template, arguments=None)
dazl.create_and_exercise(template, create_arguments, choice_name, choice_argument)
dazl.exercise(contract, choice, arguments=None)
dazl.exercise_by_key(template, contract_key, choice_name, choice_argument)
dazl.frozendict

alias of dazl.prim.map.FrozenDict

dazl.run(init: Callable[dazl.client.api.Network, None])
dazl.setup_default_logger(level=20)

Sets up a default logger with sensible defaults.

This function is deprecated, and there is no replacement; you should instead configure your own logging output as suitable for your needs (logging.basicConfig() may suffice).

with dazl.simple_client(url: Optional[str] = None, party: Union[None, str, 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.write_acs(buf: TextIO, network: Network, fmt: Optional[str] = None, include_archived: bool = False) None

Write all entries tabled by the plugin to the provided buffer.

Parameters
  • buf – The buffer to write to.

  • network – The network to write data from.

  • fmt – Format of the output; currently either "json" or "pretty".

  • include_archivedTrue to include archived contracts in the output; otherwise, False.