dazl.client package

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

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

async ensure_packages(package_ids: Collection[str], 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.

async get_time() → datetime.datetime

async metadata() → dazl.model.ledger.LedgerMetadata

Return the current set of known packages.

async set_time(new_datetime: datetime.datetime) → None

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.model.reading.ContractArchiveEvent], match: Union[None, Callable[Dict[str, Any], bool], Dict[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.model.reading.ContractCreateEvent], match: Union[None, Callable[Dict[str, Any], bool], Dict[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.model.reading.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.model.reading.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.model.reading.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.

• 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.model.reading.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.model.reading.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.model.reading.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.

find(template: Any, match: Union[None, Callable[Dict[str, Any], bool], Dict[str, Any]] = None, include_archived: bool = False) → dazl.model.core.ContractContextualDataCollection

find_active(template: Any, match: Union[None, Callable[Dict[str, Any], bool], Dict[str, Any]] = None) → Dict[dazl.model.core.ContractId, Dict[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.model.core.ContractId]) → Optional[dazl.model.core.ContractContextualData]

find_historical(template: Any, match: Union[None, Callable[Dict[str, Any], bool], Dict[str, Any]] = None) → dazl.model.core.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[Dict[str, Any], bool], Dict[str, Any]], min_count: int = 1, timeout: float = 30) → Awaitable[Dict[dazl.model.core.ContractId, Dict[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[Dict[str, Any], bool], Dict[str, Any]] = None, timeout: float = 30) → Awaitable[Tuple[dazl.model.core.ContractId, Dict[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.

get_time() → Awaitable[datetime.datetime]

Return the current time on the remote server. Also advance the local notion of time if required.

ledger_archived(template: Any, match: Union[None, Callable[Dict[str, Any], bool], Dict[str, Any]] = None) → Callable[dazl.model.reading.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[Dict[str, Any], bool], Dict[str, Any]] = None) → Callable[dazl.model.reading.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.model.reading.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.model.reading.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.model.reading.PackagesAddedEvent]

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[dazl.model.reading.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.model.reading.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.model.reading.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)

set_time(new_datetime: datetime.datetime) → Awaitable[None]

Set the current time on the ledger. This is only supported if the ledger supports time manipulation.

submit(commands: Union[None, Command, List[Optional[Command]], CommandBuilder, CommandPayload], workflow_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.

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: str, arguments: Optional[dict] = None, workflow_id: Optional[str] = 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.

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

submit_exercise(cid: dazl.model.core.ContractId, choice_name: str, arguments: Optional[dict] = None, workflow_id: Optional[str] = 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.

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

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.

aio_party(party: Union[str, NewType.<locals>.new_type]) → dazl.client.api.AIOPartyClient

Return a PartyClient that works on an asyncio event loop.

Parameters

party – The party to get a client for.

async aio_run(*coroutines, run_state: Optional[dazl.client._run_level.RunState] = None) → 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]

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.

parties() → Collection[NewType.<locals>.new_type]

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

party_bots(party: Union[str, NewType.<locals>.new_type], if_missing: typing_extensions.Literal[typing_extensions.Literal[1], typing_extensions.Literal[2], typing_extensions.Literal[3]] = typing_extensions.Literal[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, 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, 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, url: Optional[str] = None, admin_url: Optional[str] = None, **kwargs)

shutdown() → None

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

The current thread does NOT block.

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_party(party: Union[str, NewType.<locals>.new_type]) → 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_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

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[str], 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.

get_time() → datetime.datetime

metadata(timeout: Union[int, float, decimal.Decimal, str, datetime.timedelta] = 30) → dazl.model.ledger.LedgerMetadata

Return the current set of known packages.

set_time(new_datetime: datetime.datetime) → None

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

add_ledger_archived(template: Any, handler: Callable[dazl.model.reading.ContractArchiveEvent], match: Union[None, Callable[Dict[str, Any], bool], Dict[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.model.reading.ContractCreateEvent], match: Union[None, Callable[Dict[str, Any], bool], Dict[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.model.reading.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.model.reading.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.model.reading.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.

• 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.model.reading.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.model.reading.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.model.reading.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.

find(template: Any, match: Union[None, Callable[Dict[str, Any], bool], Dict[str, Any]] = None, include_archived: bool = False) → dazl.model.core.ContractContextualDataCollection

find_active(template: Any, match: Union[None, Callable[Dict[str, Any], bool], Dict[str, Any]] = None) → Dict[dazl.model.core.ContractId, Dict[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.model.core.ContractId]) → Optional[dazl.model.core.ContractContextualData]

find_historical(template: Any, match: Union[None, Callable[Dict[str, Any], bool], Dict[str, Any]] = None) → dazl.model.core.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[Dict[str, Any], bool], Dict[str, Any]], min_count: int = 1, timeout: float = 30) → Dict[dazl.model.core.ContractId, Dict[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[Dict[str, Any], bool], Dict[str, Any]] = None, timeout: float = 30) → Tuple[dazl.model.core.ContractId, Dict[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.

get_time() → datetime.datetime

ledger_archived(template: Any, match: Union[None, Callable[Dict[str, Any], bool], Dict[str, Any]] = None) → Callable[dazl.model.reading.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[Dict[str, Any], bool], Dict[str, Any]] = None) → Callable[dazl.model.reading.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.model.reading.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.model.reading.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.model.reading.PackagesAddedEvent]

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[dazl.model.reading.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.model.reading.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.model.reading.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)

set_time(new_datetime: datetime.datetime) → None

submit(commands, workflow_id: str = None) → None

submit_create(template_name: Union[str, dazl.model.types.TypeReference, dazl.model.types.UnresolvedTypeReference, dazl.model.types.Template], arguments: Optional[dict] = None, workflow_id: Optional[str] = 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.

submit_create_and_exercise(template_name: Union[str, 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) → 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.

submit_exercise(cid: dazl.model.core.ContractId, choice_name: str, arguments: Optional[dict] = None, workflow_id: Optional[str] = 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.

submit_exercise_by_key(template_name: Union[str, 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) → 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.

dazl.client.api.simple_client(url: Optional[str] = None, party: Union[None, str, Party] = None, log_level: Optional[int] = 20) → ContextManager[SimplePartyClient]

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[E, Any], filter_fn: Optional[Callable[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

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

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

Return True if this bot is currently processing events.

property state

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[NewType.<locals>.new_type])

Bases: typing.Sequence

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.model.reading.BaseEvent)

stop_all()

class dazl.client.bots.BotEntry(event_key:str, callback:Callable[[~E], Any], filter:Union[Callable[[~E], bool], NoneType]=None, source_location:Union[dazl.model.core.SourceLocation, NoneType]=None)

Bases: object

filter = None

source_location = None

class dazl.client.bots.BotInvocation(event:dazl.model.reading.BaseEvent, future:_asyncio.Future=<factory>)

Bases: object

class dazl.client.bots.BotState

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'

dazl.client.bots.wrap_as_command_submission(submit_fn, callback, filter) → Callable[dazl.model.reading.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.