TallwrightDocs

Python API reference

Every public name of tallwright_cloud, its signature, and what it promises, in the package's own words. Written from the package by scripts/render_api_reference.py; how the pieces fit together is in the SDK's README.

Clients

Tallwright

Tallwright(url: str, key: str, evidence: str | os.PathLike[str] | EvidenceStore, *, timeout: float = 30.0, on_problem: Problem | None = None, sender: Sender | None = None)

A client of one recording door, keeping the evidence of its records in one store.

  • acapture(content: object, *, action_type: str | None = None, actor_authority: str | None = None, record_id: str | None = None, timestamp: str | None = None) -> Capture: capture, from a coroutine: committed here, written and sent off the event loop.
  • asubmit(content: object, *, action_type: str | None = None, actor_authority: str | None = None, record_id: str | None = None, timestamp: str | None = None) -> str: submit, from a coroutine: committed here, the evidence written off the event loop.
  • capture(content: object, *, action_type: str | None = None, actor_authority: str | None = None, record_id: str | None = None, timestamp: str | None = None) -> Capture: Record one event and wait for the door's receipt: the content stays here, its address goes.
  • close(timeout: float | None = 10.0) -> Flushed: Flush, and end this client's own sending thread. What is left stays pending in the evidence.
  • evidence: The store this client keeps its evidence in: the content, the salt, the line and the receipt.
  • flush(timeout: float | None = 30.0) -> Flushed: Wait up to timeout seconds for what was submitted; what is still to be sent, and why.
  • pending() -> list[str]: Records sent under this key and never confirmed or refused, which resend may send again.
  • resend(record_id: str, *, adopt: bool = False) -> Capture: Send a pending record's line again, byte for byte. Already held is a confirmation too.
  • resend_pending(*, timeout: float | None = 30.0) -> Flushed: Lift a stop, queue every record pending under this key for the background sender, and flush.
  • save_exhibit(link: str) -> str: Open a one-time exhibit link and file the exhibit beside the record it is of; where it is.
  • session: The sixteen hex digits every name this client mints in this process begins with.
  • status() -> Status: What this client's background sending is doing now: how many records wait, and why it stopped.
  • submit(content: object, *, action_type: str | None = None, actor_authority: str | None = None, record_id: str | None = None, timestamp: str | None = None) -> str: Record one event without waiting for the door; its name, once its evidence is safe.

Environments

Environments(url: str, key_for: Callable[[str], str], evidence: str | os.PathLike[str] | EvidenceStore, *, timeout: float = 30.0, on_problem: Problem | None = None)

One Tallwright per end customer, made on first use, sharing one sender.

  • client(customer_ref: str) -> Tallwright: The client of customer_ref's Environment, with its evidence beneath customer_ref.
  • close(timeout: float | None = 10.0) -> Flushed: Flush, and end the one sending thread every customer's client shares. What is left stays pending.
  • flush(timeout: float | None = 30.0) -> Flushed: Wait up to timeout seconds for what every customer's client submitted; what is still to be sent.
  • forget(customer_ref: str) -> None: Drop a customer's client, after its key was replaced: the next client asks key_for again.

Exhibits

Exhibits(url: str, export_key: str, evidence: str | os.PathLike[str] | EvidenceStore, *, timeout: float = 30.0)

An environment's exhibits, taken with its export key, filed beside the records this evidence sent.

  • evidence: The store the exhibits are filed in, beside the records this evidence sent.
  • save(record_id: str) -> str: Take the exhibit of one record this evidence sent and file it beside the record; where it is.

Account

Account(url: str, account_key: str, *, timeout: float = 90.0)

The account API of one account, with its account key: it makes, finds, re-keys and closes Environments.

  • close(environment: str) -> Environment: Close an Environment when its customer leaves. Its log stays and still exports.
  • create(name: str, *, customer_ref: str, deployer_label: str) -> Made: Make an Environment for one end customer; its key is in the answer, once.
  • environments(*, status: str | None = None, customer_ref: str | None = None) -> Iterator[Environment]: Every Environment of the account, page by page, in the order the API keeps them.
  • find(customer_ref: str) -> Environment | None: The open Environment of customer_ref, or None.
  • new_key(environment: str) -> Made: Replace an Environment's recording key: the old one stops at once, the new one is here once.

What a call answers

Capture

Capture(record_id: str, payload_hash: str, receipt: Receipt, evidence: str, disclosure: str, warning: str | None = None)

A record the door confirmed holding: its name, its address, the receipt and where its pair is.

Receipt

Receipt(record_id: str, status: str, leaf_index: int, record_hash: str, prev_record_hash: str | None, timestamp: str, timestamp_source: str, log_size: int, note: str, as_written: dict[str, Any])

Where the door says this record is, and who set its time. A confirmation, not a proof.

  • read(answer: object, record_id: str) -> Receipt: The door's receipt for record_id, or UnreadableReceipt saying what is wrong.

Status

Status(queued: int, stopped: str | None)

What a client's background sending is doing now.

Flushed

Flushed(pending: int, stopped: tuple[str, ...] = ())

What a flush left: how many records are still to be sent, and the clients that were stopped.

  • complete: Whether nothing is left to send and no client was stopped.

Environment

Environment(id: str, name: str, customer_ref: str | None, deployer_label: str, environment_id: str | None, status: str, reason: str | None = None, created_at: str | None = None, closed_at: str | None = None)

One Environment as the account API shows it.

  • read(given: object) -> Environment: An Environment from one entry of the account API's answer; AccountError when it is not one.

Made

Made(environment: Environment, ingest_url: str, key: Secret)

An Environment just made, or given a new key: the key is here once, and nowhere else.

Secret

Secret(value: str)

A key shown once. reveal it into the secret store; nothing else shows more than its face.

  • reveal() -> str: The key itself, for the one place it is handed to; everything else is shown its first characters.

Where the evidence is kept

EvidenceStore

EvidenceStore(*args, **kwargs)

What the SDK needs of the place that keeps its evidence: create, never replace, and durable on return.

  • check() -> list[str]: What stands in the way of this store keeping evidence; empty when nothing does.
  • children(prefix: str) -> list[str]: The names one level below prefix ("" is the top), files and folders alike, sorted.
  • create(name: str, data: bytes) -> None: Write a new object, durable on return. FileExistsError if name is taken.
  • locate(name: str) -> str: Where name is, for a person: a path, or an s3:// address; "" is the store itself.
  • read(name: str) -> bytes | None: The object's bytes, or None when there is none under name.
  • remove(name: str) -> None: Remove an outbox marker, a chain note or a probe. Never called on evidence.
  • within(part: str) -> EvidenceStore: The same store, beneath part: one Environment's evidence apart from another's.

LocalEvidence

LocalEvidence(root: str | os.PathLike[str], *, ephemeral_ok: bool = False)

Evidence in a directory: one folder per record, the owner's alone on POSIX (0700, files 0600).

Implements EvidenceStore; what is beyond it:

  • path(name: str) -> Path: Where name is on disk, once the name is checked: a name cannot lead out of the evidence directory.

S3Evidence

S3Evidence(client: Any, bucket: str, *, prefix: str = '')

Evidence in a bucket, through an S3 client the integrator made and configured.

Implements EvidenceStore; what is beyond it:

Functions

gaps

gaps(record_ids: Iterable[str]) -> dict[str, list[int]]

For every session among these names, the numbers missing below the highest one seen.

Errors

Every error about a record, the door, the evidence, an exhibit or the account is a TallwrightError; an argument the package cannot use is refused with a TypeError or ValueError. Each line names what it is a kind of.

  • TallwrightError (Exception): Anything this client refuses or could not complete. record_id says which record, or "".
  • NotConfirmed (TallwrightError): No receipt for this record. It is pending, and resend(record_id) may be called.
  • Unauthorized (NotConfirmed): 401: the key is not one the door holds. Pending, bound to the key it was written under: once the right key is in place, resend(record_id, adopt=True) sends it under that key.
  • AccountClosed (NotConfirmed): 403: the account behind the key is closed. Pending; nothing is recorded until it reopens.
  • Refused (TallwrightError): The door read this line and refused it in its own sentence. Not pending; the same line will not be accepted.
  • RecordIdConflict (Refused): 409: the door holds a record under this record_id that differs from this line.
  • LostByTheDoor (TallwrightError): Records the door receipted and its log no longer holds. Pending again; resend records each anew.
  • EvidenceError (TallwrightError): The evidence directory could not do its part. When it fails before sending, nothing was sent.
  • ExhibitError (TallwrightError): No exhibit of a record in this evidence directory was handed over, by a link or for an export key. Nothing was filed.
  • ExhibitNotReady (ExhibitError): 409: the door could not build the exhibit now, and says why — most often that no witness has covered the record yet. Nothing was used by asking: a link opens again until it expires, and an export key may simply ask again after the next anchor run.
  • LinkSpent (ExhibitError): 410: the link was used once already, which is all it was good for. Ask for a new one.
  • ExportKeyRefused (ExhibitError): 401: the exhibit door holds no such export key — never issued, replaced by a newer one, or withdrawn. Nothing was filed; the backoffice issues a new one.
  • AccountError (TallwrightError): The account API refused or could not complete a request, in its own sentence where it gave one.
  • EnvironmentExists (AccountError): 409: an open Environment for this customer_ref exists, and nothing was made.