`dazl.ledger.aio`¶

asyncio-flavored protocols and base classes for connecting to a Daml ledger.

This protocol is currently implemented by the asyncio gRPC Ledger API implementation dazl.ledger.grpc.conn_aio.Connection.

class dazl.ledger.aio.Connection¶

codec¶: The codec object.

config¶: The dazl.ledger.config.Config that was used to initialize this connection.

await open()¶: Open the connection. Will also fetch the ledger ID if that information is not locally available.

await close()¶: Close the connection. Commands in-flight will be allowed to finish, but new commands will be rejected. All existing streams made from this connection are closed.

await create(template_id, payload, /, *, workflow_id=None, command_id=None)¶

Create a contract for a given template.

Parameters

template_id (str or dazl.damlast.TypeConName) – The template of the contract to be created.
payload (dict) – Template arguments for the contract to be created.
workflow_id (str or None) – An optional workflow ID.
command_id (str or None) – An optional command ID. If unspecified, a random one will be created.

Returns

The dazl.ledger.CreateEvent that describes the created contract, including its contract ID.

await create_and_exercise(template_id, payload, choice_name, [argument, ]/, *, workflow_id=None, command_id=None)¶

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

Parameters

contract_id (dazl.prim.ContractId) – The contract ID of the contract to exercise.
choice_name (str) – The name of the choice to exercise.
argument (dict or None) – The choice arguments. Can be omitted for choices that take no argument.
workflow_id (str or None) – An optional workflow ID.
command_id (str or None) – An optional command ID. If unspecified, a random one will be created.
workflow_id – An optional workflow ID.
command_id – An optional command ID. If unspecified, a random one will be created.

Returns

dazl.ledger.ExerciseResponse containing the return value of the choice, together with a list of events that occurred as a result of exercising the choice.

await exercise(contract_id, choice_name, [argument, ]/, *, workflow_id=None, command_id=None)¶

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

Parameters

contract_id (dazl.prim.ContractId) – The contract ID of the contract to exercise.
choice_name (str) – The name of the choice to exercise.
argument (dict or None) – The choice arguments. Can be omitted for choices that take no argument.
workflow_id (str or None) – An optional workflow ID.
command_id (str or None) – An optional command ID. If unspecified, a random one will be created.

Returns

dazl.ledger.ExerciseResponse containing 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(template_id, choice_name, key, [argument, ]/, *, workflow_id=None, command_id=None)¶: Exercise a choice on a contract identified by its contract key.

await submit(commands, /, *, workflow_id=None, command_id=None)¶

Submit one or more commands to the Ledger API.

You should generally prefer trying to use create(), exercise(), exercise_by_key(), or create_and_exercise(), as they are available over both the gRPC Ledger API and HTTP JSON API; additionally those methods can provide more information about what happened.

This method can be used to submit multiple disparate commands as a single transaction, but if you find yourself needing to do this, you may want to consider moving more of your logic into Daml so that only a single command is needed from the outside in order to satisfy your use case.

Parameters

commands (dazl.ledger.Command or list[dazl.ledger.Command]) – The sequence of commands to submit to the ledger.
workflow_id (str or None) – An optional workflow ID.
command_id (str or None) – An optional command ID. If unspecified, a random one will be created.

query([template_id, ][query, ]/)¶

stream([template_id, ][query, ]/, *, offset=None)¶

Parameters

template_id (str or dazl.damlast.TypeConName) – The name of the template for which to fetch contracts. If omitted or “*”, contracts for all templates are returned.
query – A dict whose keys represent exact values to be matched.
offset (str or None) – An optional offset at which to start receiving events. If None, start from the beginning. Can only be supplied to stream().

Returns

A QueryStream over the relevant events.

The stream returned by query() represents a snapshot of the current state, and terminates when all CreateEvent instances that represent currently active contracts are returned.

The stream returned by stream() returns the current state as query() does, but afterwards the stream remains open, and subsequent CreateEvent and ArchiveEvent’s are returned until close() is called.

query_many(*queries)¶
stream_many(*queries, offset=None)¶

class dazl.ledger.aio.QueryStream¶

Protocol for classes that provide for asynchronous reading from a stream of events from a Daml ledger.

Reading from and controlling the stream

The creates(), events(), and items() methods are used to receive events from the stream; run() can be used to consume the stream without iterating yourself, and close() stops the stream. These methods consume the stream: you cannot replay a QueryStream’s contents simply by trying to iterate over it again.

async with conn.stream() as stream:
    async for event in stream.creates():
        # print every contract create...forever
        print(event.contract_id, event.payload)

Note that the events() and items() streams may return ArchiveEvent objects that had no CreateEvent predecessor. This may happen for a number of reasons:

You started requesting a stream at a specific offset. When resuming from an offset, no events (CreateEvent or ArchiveEvent) that preceded the specified offset are returned.
You are filtering events; event filtering only applies to CreateEvent instances and not ArchiveEvent.
You are learning of an archive of a divulged contract. Note that dazl does not have an API for retrieving divulged contracts.

abstractmethod async for event in creates()¶: Return an iterator (or async iterator) over only CreateEvent instances.

abstractmethod async for event in events()¶: Return an iterator (or async iterator) over CreateEvent and ArchiveEvent instances.

abstractmethod async for event_or_boundary in items()¶: Return an iterator (or async iterator) over all objects (CreateEvent, ArchiveEvent, and Boundary).

abstractmethod await run()¶: Block until the stream has been fully consumed. This method normally only makes sense to use in conjunction with callbacks (on_create(), on_archive(), and on_boundary()).

abstractmethod await close()¶: Stops the iterator and aborts the stream. For async connections, this is a coroutine.

Registering Callbacks

Callbacks can be used as an alternative to reading events from the stream.

The callable must take a CreateEvent, ArchiveEvent, or Boundary as its only parameter and should generally return None. However the callback can also return CreateEvent or ExerciseResponse, mostly so that one-line lambdas that call ledger methods can be used:

# registering a callback as a lambda
stream.on_create("My:Tmpl", lambda event: conn.exercise(event.cid, "Accept"))

# registering a callback using a decorator
@stream.on_create("My:Tmpl")
def handle(event):
    conn.exercise(event.cid, "Accept")

on_create(fn)¶

on_create(name, fn)

@on_create

@on_create(name)

Parameters: name (str or TypeConName) – An optional name of a template to further filter CreateEvent.

on_archive(fn)¶

on_archive(name, fn)

@on_archive

@on_archive(name)

Parameters: name (str or TypeConName) – An optional name of a template to further filter ArchiveEvent.

on_boundary(fn)¶
@on_boundary: Register a callback that is triggered whenever a Boundary is read through the stream.

dazl.ledger.aio¶

`dazl.ledger.aio`¶