Python SDK Reference

Generated statically from the package’s literal warmhub.__all__ with Griffe. The generator never imports the SDK.

This build documents 304 root exports and 27 client namespace projections.

Client namespaces

• client
• client.access
• client.action
• client.auth
• client.collection
• client.commit
• client.component
• client.component.cli
• client.component.registry
• client.credential
• client.diagnostics
• client.homepage
• client.org
• client.org.service_accounts
• client.repo
• client.repo.checkpoint
• client.repo.index
• client.shape
• client.stream
• client.subscription
• client.thing
• client.token
• client.view
• repository
• repository.repo
• repository.repo.checkpoint
• repository.things

Classes

• AboutResult — Generated from AboutResult.
• AccessResolveResult — Generated from AccessResolveResult.
• ActionAttempt — Generated from ActionAttempt.
• ActionLeaseAcquire0 — Generated from ActionLeaseAcquire0.
• ActionLeaseAcquire1 — Generated from ActionLeaseAcquire1.
• ActionLeaseOp0 — Generated from ActionLeaseOp0.
• ActionLeaseOp1 — Generated from ActionLeaseOp1.
• ActionListRunsResult — Generated from ActionListRunsResult.
• ActionLiveFeedResult — Generated from ActionLiveFeedResult.
• ActionLiveFeedResultItemsItem — Generated from ActionLiveFeedResultItemsItem.
• ActionNotification — Generated from ActionNotification.
• ActionRun — Generated from ActionRun.
• ActionRunStats — Generated from ActionRunStats.
• Add — Create the Thing name, stating its Shapes (shapes or shapeless).
• AffirmationDelta — The per-target outcome of a reaffirm or affirmed-targets write.
• AllStreamOperationsFailedError — The stream append completed deterministically but every operation failed.
• Assertion — Generated from Assertion.
• AsyncBoundRepoNamespace — The repo namespace with org_name/repo_name bound.
• AsyncBoundThingNamespace — repository.things — AsyncThingNamespace with the repo bound.
• AsyncOperationBuilder — The awaitable half of the pair.
• AsyncRepositoryClient — A repository-bound view of the client’s namespaces.
• AsyncRepositoryExportStream — The async for twin of RepositoryExportStream.
• AsyncTransport — Issues tRPC calls over an httpx.AsyncClient.
• AsyncWarmHubClient — Asynchronous WarmHub client.
• AuthProvider — The auth constructor option: an object exposing get_token.
• AuthSyncResult — Generated from AuthSyncResult.
• Capabilities — Generated from Capabilities.
• CheckpointArchiveError — The archive is not a canonical repository checkpoint ZIP64 file.
• CheckpointChunkError — A record chunk is invalid, malformed, or not canonically encoded.
• CheckpointManifestError — The manifest is invalid, malformed, or not canonically encoded.
• CheckpointSourceReadError — The caller-provided archive source could not be read as bytes.
• ClientIdentity — name/version stamped on the X-WarmHub-Client header.
• CoalescedWrefWarning — A wref that resolved to nothing and was folded away rather than stored.
• CollectionContainsResult — Generated from CollectionContainsResult.
• CollectionDiffResult — Generated from CollectionDiffResult.
• CollectionMembersPage — Generated from CollectionMembersPage.
• CollectionMembersPageItemsItem — Generated from CollectionMembersPageItemsItem.
• CollectionMutationCompatibilityResult0 — Generated from CollectionMutationCompatibilityResult0.
• CollectionMutationCompatibilityResult1 — Generated from CollectionMutationCompatibilityResult1.
• CollectionStatsResult — Generated from CollectionStatsResult.
• CommitApplyCompatibilityResult0 — Generated from CommitApplyCompatibilityResult0.
• CommitApplyCompatibilityResult1 — Generated from CommitApplyCompatibilityResult1.
• CommitOptions — Per-commit knobs shared by repo.apply and OperationBuilder.
• CommitValidateResult — Generated from CommitValidateResult.
• ComponentDetail — Generated from ComponentDetail.
• ComponentHistoryResult — Generated from ComponentHistoryResult.
• ComponentInstallResult — Generated from ComponentInstallResult.
• ComponentListResult — Generated from ComponentListResult.
• ComponentListResultItemsItem — Generated from ComponentListResultItemsItem.
• ComponentRegistryInfo — Generated from ComponentRegistryInfo.
• ComponentRegistryList — Generated from ComponentRegistryList.
• ComponentRegistryResolveResult — Generated from ComponentRegistryResolveResult.
• ComponentRegistrySetupCallResult — Generated from ComponentRegistrySetupCallResult.
• ComponentRegistryUnregisterResult — Generated from ComponentRegistryUnregisterResult.
• ComponentUninstallResult — Generated from ComponentUninstallResult.
• CountResult — Generated from CountResult.
• CredentialAuditEntry — Generated from CredentialAuditEntry.
• CredentialDeleteResult — Generated from CredentialDeleteResult.
• CredentialInfo — Generated from CredentialInfo.
• CredentialKeyMutationResult — Generated from CredentialKeyMutationResult.
• CredentialRevokeResult — Generated from CredentialRevokeResult.
• DeprecationNotice — A shape that still works and will stop working.
• DuplicateCheckpointDurableIdError — Two checkpoint rows advertise the same durable identity.
• ExpectedVersionMismatch — Optimistic-concurrency precondition failed (#3624).
• FieldIndexPinResult — Generated from FieldIndexPinResult.
• GlobalSearchResult — Generated from GlobalSearchResult.
• GlobalSearchResultItem — Generated from GlobalSearchResultItem.
• HeadResult — One page of a list read.
• HistoryResult — Generated from HistoryResult.
• HomepageFeaturedListsResult — Generated from HomepageFeaturedListsResult.
• IgnoredVersionPin — An authored @vN (or versioned storage token) dropped on an identity-bound leaf: the reference follows the Thing, so the pin carried no meaning. binding names the effective mode that governed.
• IndexedFieldsReport — Generated from IndexedFieldsReport.
• LeaseHeld — A live read lease blocks this mutation or acquire (#3625).
• NameTaken — A write claimed a name another active Thing in the repo holds (#11219).
• NameTakenBy — The active Thing that holds a refused name, by durable id.
• OldName — A Thing read named an old Shape/name spelling (#12575).
• OperationBuilder — Fluent builder for composing, validating, and submitting operations.
• OperationError — One diagnostic explaining why an operation did not land.
• OperationEventHeader — Persisted event metadata, absent when an append produced no event.
• OperationEventReceipt — Exact immutable acknowledgement for one stream chunk.
• OperationEventReceipt0 — Generated from OperationEventReceipt0.
• OperationEventReceipt1 — Generated from OperationEventReceipt1.
• OperationEventReceiptMetadata — Generated from OperationEventReceiptMetadata.
• OperationEventReceiptV1 — Generated from OperationEventReceiptV1.
• OperationEventReceiptV2 — Generated from OperationEventReceiptV2.
• OperationEventRepo — Repository identity embedded in an immutable operation-event receipt.
• OperationWarnings — Everything a write succeeded despite, for one operation.
• Org — Generated from Org.
• OrgGetResult — Generated from OrgGetResult.
• OrgListResponse — Generated from OrgListResponse.
• OrgMember — Generated from OrgMember.
• OrgMemberList — Generated from OrgMemberList.
• PartialStreamSubmissionError — A streamed commit failed after an ambiguous or partial append.
• PatternCheckSkipped — A pattern constraint was not evaluated because RE2 is absent.
• PayloadDecodeError — A read’s data could not be decoded into the requested shape.
• PingResult — Generated from PingResult.
• RateLimitReset — A rate limit rejected the request until a reset time.
• RawSnapshot — as_dict() for the models that carry a wire raw.
• Reaffirm — Edit an assertion’s affirmation snapshot without changing claim data.
• ReceiptOperation — One exact operation row from a durable event receipt.
• RefsResult — Generated from RefsResult.
• RefsResultItemsItem — Generated from RefsResultItemsItem.
• RemoveCompatibilityResult — Generated from RemoveCompatibilityResult.
• Rename — Rename the Thing name to new_name, both full names.
• RenameCompatibilityResult0 — Generated from RenameCompatibilityResult0.
• RenameCompatibilityResult1 — Generated from RenameCompatibilityResult1.
• RepoConfigureStats — Generated from RepoConfigureStats.
• RepoDeleteResult — Generated from RepoDeleteResult.
• RepoDescribeResult — Generated from RepoDescribeResult.
• RepoExploreResult — Generated from RepoExploreResult.
• RepoExploreResultItemsItem — Generated from RepoExploreResultItemsItem.
• RepoForCaller — Generated from RepoForCaller.
• RepoInfo — A repository’s metadata. Mirrors RepoInfo in the TypeScript SDK.
• RepoLicense — Generated from RepoLicense.
• RepoListPageResult — Generated from RepoListPageResult.
• RepoListResult — Generated from RepoListResult.
• RepoListResultItemsItem — Generated from RepoListResultItemsItem.
• RepoStats — Generated from RepoStats.
• RepoStatsBatchResult — Generated from RepoStatsBatchResult.
• RepoWithStatsInfo — Generated from RepoWithStatsInfo.
• RepositoryCheckpointAccess — A short-lived descriptor for one checkpoint artifact download.
• RepositoryCheckpointArchive — Integrity metadata for a completed checkpoint archive.
• RepositoryCheckpointComplete — Completed checkpoint with manifest and archive descriptors.
• RepositoryCheckpointFailedAttemptsExhausted — Checkpoint generation exhausted its attempts. Terminal: generation is retired.
• RepositoryCheckpointFailedContactSupport — Checkpoint failed with an integrity or contract problem requiring support.
• RepositoryCheckpointFailedDeadlineExceeded — Checkpoint generation exceeded its deadline. Terminal: generation is retired.
• RepositoryCheckpointFailedInvalidSource — Checkpoint source was invalid. Terminal: generation is retired.
• RepositoryCheckpointFailedRepositoryDeleted — Checkpoint stopped because its repository was deleted.
• RepositoryCheckpointManifest — Integrity metadata for a completed checkpoint manifest.
• RepositoryCheckpointQueued — Checkpoint generation is queued; poll for progress.
• RepositoryCheckpointRunning — Checkpoint generation is running; poll for progress.
• RepositoryCheckpointVerificationError — A server-free checkpoint verification failure with no repository data.
• RepositoryCheckpointVerificationExpected — Integrity and identity facts advertised by a checkpoint access descriptor.
• RepositoryCheckpointVerificationResult — Verified identity, counts, and digests for a complete checkpoint archive.
• RepositoryClient — The synchronous repository handle.
• RepositoryExportError — A repository export failed to read, verify, or be served.
• RepositoryExportHeader — The first line of every export segment.
• RepositoryExportPending — The server is still building the export behind a token.
• RepositoryExportReader — Verifies one logical export, across one or more transport segments.
• RepositoryExportStream — Validated rows, plus the reader holding the header, counts and digest.
• RepositoryExportTicket — An asynchronously built export, not yet ready to read.
• RepositoryExportTrailer — The last line of a segment, carrying that segment’s integrity claim.
• RepositoryExportVerification — A saved export that re-verified end to end with no network access.
• RepositoryLocator — The organization and repository a handle is bound to.
• RequestPlan — Everything about a tRPC call that is decided before any I/O happens.
• Restore — Make a retracted Thing active again, named by its durable ID.
• Retract — Mark the Thing name retracted in a new version.
• RetryPolicy — Knobs for the write path’s transient first-chunk retry.
• Revise — Replace the data of the Thing name, stating its Shapes (shapes, shapeless or keep_shapes).
• RewriteCompatibilityResult — Generated from RewriteCompatibilityResult.
• ServiceAccount — Generated from ServiceAccount.
• ShapeGetResult — Generated from ShapeGetResult.
• ShapeListResult — Generated from ShapeListResult.
• ShapeRemoveCompatibilityResult0 — Generated from ShapeRemoveCompatibilityResult0.
• ShapeRemoveCompatibilityResult1 — Generated from ShapeRemoveCompatibilityResult1.
• ShapeValidationResult — Local shape-validation verdict with blocking errors and warnings.
• StreamAppendResult0 — Generated from StreamAppendResult0.
• StreamAppendResult1 — Generated from StreamAppendResult1.
• StreamStatusCounts — Aggregate operation outcomes for a streamed submission.
• StreamValidationError — Client-side validation rejected a streamed submission before transport.
• SubmitResult — What a completed commit submission returns.
• SubmittedOperation — One row of a stream-append result.
• SubscriptionBindCredentialsResult — Generated from SubscriptionBindCredentialsResult.
• SubscriptionInfo — Generated from SubscriptionInfo.
• SubscriptionPauseResult — Generated from SubscriptionPauseResult.
• SubscriptionRemoveResult — Generated from SubscriptionRemoveResult.
• SubscriptionResumeResult — Generated from SubscriptionResumeResult.
• SubscriptionRevealResult — Generated from SubscriptionRevealResult.
• SubscriptionUnbindCredentialsResult — Generated from SubscriptionUnbindCredentialsResult.
• SyncBoundRepoNamespace — The synchronous repo namespace with org_name/repo_name bound.
• SyncBoundThingNamespace — repository.things — SyncThingNamespace with the repo bound.
• SyncTransport — Issues tRPC calls over an httpx.Client.
• SynthesizedRepoContent — Generated from SynthesizedRepoContent.
• TRPCClientError — Carrier for a tRPC error envelope.
• TargetRemoved — A new reference or dependency named a removed Thing (#11477).
• ThingChanges — A completed incremental scan: every change, and where the scan ended.
• ThingDetail — Full record shape for a single-record read.
• ThingGetManyResult — Generated from ThingGetManyResult.
• ThingGetWithLease — Generated from ThingGetWithLease.
• ThingGraphResult — Generated from ThingGraphResult.
• ThingHeadVersionsResult — Generated from ThingHeadVersionsResult.
• ThingItem — A row from a list read (thing.head, query, search).
• ThingNamesResult — Generated from ThingNamesResult.
• TokenCreateResult — Generated from TokenCreateResult.
• TokenInfo — Generated from TokenInfo.
• TokenRevokeResult — Generated from TokenRevokeResult.
• UndeclaredFieldsWarning — Fields present in data but absent from the supplied shape declaration.
• UndecodableAppendResponse — The append response was invalid and its durable outcome is unknown.
• UnknownErrorDetails — Forward compatibility: a reason this client does not know yet.
• ValidationDiagnostic — One local builder diagnostic tied to an operation index.
• ValidationFailed — Request input validation failed, with per-field issues.
• ValidationIssue — One field-level request validation failure.
• ValidationResult — What OperationBuilder.validate returns — never a bare bool.
• ViewEvaluateResult — Generated from ViewEvaluateResult.
• WarmHubClient — Synchronous WarmHub client.
• WarmHubError — Normalized error for transport, tRPC, validation, and backend failures.
• WarmHubException — Root of every exception the SDK raises.
• WhereField — A bound field path awaiting an operator. Returned by where.
• WherePredicate — One field-value predicate, ready to serialize.
• WhoamiInfo0 — Generated from WhoamiInfo0.
• WhoamiInfo1 — Generated from WhoamiInfo1.
• WireDecodeError — The server payload did not match the wire contract.
• WireThingDetail — Generated from ThingDetail.
• WriteOperationError — A local write refusal, before any request.

Functions

• aopen_repository_export — The async twin of open_repository_export.
• aopen_repository_export_token — The async twin of open_repository_export_token.
• apply_repository_export_delta — Fold a delta export over a base, keyed by durable identity.
• arequest_repository_export — The async twin of request_repository_export.
• assert_content_within_limit — Refuse a content field that exceeds the canonical byte limit.
• connection_error_message — Canonical user-facing message for a connection-level failure.
• content_field_limit_error — The message for an oversized content field, or None if it fits.
• create_operation_event_request_id — Alias for operation_event_stream_request_id using generic event wording.
• create_operation_event_submission_id — Mint the canonical UUID shared by one logical submission’s chunks.
• is_conflict — Whether error is a lost race: re-read, re-apply, retry.
• is_connection_error — Whether error is a connection-level failure raised before a response.
• is_known_checkpoint_content_type — Whether this SDK build recognizes a checkpoint access media type.
• is_known_component_install_result_state — Return whether this build recognizes the install health state.
• is_known_component_summary_state — Return whether this build recognizes the installation lifecycle state.
• is_known_credential_scope — Return whether this build recognizes the credential scoping level.
• is_known_global_search_result_item_kind — Return whether this build recognizes the global search result kinds.
• is_known_homepage_featured_item_kind — Return whether this build recognizes the homepage item kind.
• is_known_org_auth_scope — Is value one of the org scopes this build knows about?
• is_known_org_member_status — Return whether this build recognizes the organization membership statuses.
• is_known_org_role — Return whether this build recognizes the organization role.
• is_known_repo_auth_scope — Is value one of the repo scopes this build knows about?
• is_known_subscribable_event_type — Return whether this build recognizes the subscription event type.
• is_not_found — Whether the target does not exist. The create-if-missing branch.
• is_rate_limited — Whether a rate limit rejected the request.
• is_retryable — Whether an error kind is generally safe to retry.
• is_transport_error — Whether error came from the transport rather than from the backend.
• is_validation_error — Whether the request was rejected as malformed.
• is_warmhub_error — Whether error is already a WarmHubError.
• normalize_wref — Remove an @vN, @HEAD, or @ALL version suffix from a wref.
• open_repository_export — Stream a repository export, verifying every line as it arrives.
• open_repository_export_token — Redeem an export token: the stream, or the state it is still in.
• operation_event_stream_request_id — Derive the ratified UUIDv5 request identity for one stream chunk.
• parse_repository_locator — Parse "org/repo" or "wh:org/repo/..." into its two names.
• request_repository_export — Ask the server to build the export in the background.
• shape_decoder — Build a decoder for a dataclass whose fields are the data keys.
• shape_name — 'Deal' -> 'hub/shapes/Deal': the name a Shape is written under.
• to_warmhub_error — Normalize any thrown value into a WarmHubError.
• validate_against_shape — Validate data against a shape’s field definitions.
• verify_repository_checkpoint_archive — Stream and verify a repository checkpoint archive without network access.
• verify_repository_export_file — Re-verify a saved export end to end, with no network access.
• where — Start a field-value predicate for thing.head, query, count.

Types

• AccessTokenProvider — A static token, or a sync/async callable returning one.
• ActionLeaseOp — Action lease acquisition or release operation.
• ActionRunStatus — action.listRuns’s run-status vocabulary, named once rather than spelled out in all four places (both Protocols and both iterators) where a divergence would be a Literal that silently accepts less than the generated method.
• CheckpointArtifact — Checkpoint artifact selected for a short-lived download descriptor.
• CollectionMutationCompatibilityResult — Compatibility response returned by collection mutation endpoints.
• CollectionReadDataMode — How much of each record’s data thing.get and get_many return: “auto” or “full”. The server accepts nothing else on those reads (and on resolve).
• CollectionRole — Which end of a resolved collection assertion the target must occupy.
• CommitOperationKind — Stored entity kind targeted by a commit operation.
• DataMode — How much of each record’s data the head family (thing.head, head_iter, head_all, changes) returns. thing.get, get_many and resolve accept only CollectionReadDataMode (“auto” | “full”), as the server does.
• ErrorDetails — Structured corrective detail attached to a WarmHubError.
• ExtraBody — Per-call body keys the SDK does not model. Unmodelled by design; see above.
• ExtraHeaders — Per-call headers. Merged over the client’s defaults, but never over auth: assemble_headers re-stamps the resolved bearer afterwards, so a caller cannot substitute a different authorization for one call.
• ExtraQuery — Per-call query parameters, merged into the URL’s existing query rather than replacing it. See merge_extra_query for why that distinction is load-bearing.
• HistoryVersion — JSON payload stored for one history version.
• JsonMapping — A JSON object. What a mapping-based decoder is handed, and the type an undecoded data must be narrowed to before it can be indexed.
• JsonValue — Anything a JSON document can hold, defined recursively.
• NameMatch — Deterministic literal name matching, or ranked search.
• Nullable — T | None — a required nullable field. The key is always sent.
• NullableOmittable — T | None | Unset — a nullable optional field, all three states live.
• Omittable — T | Unset — an optional field. Absent means the key is not sent.
• Operation — The public write contract. Discriminated on the operation attribute.
• OperationInput — Public operation objects or equivalent JSON mappings accepted by validation.
• PayloadDecoder — What decoder accepts. Named so signatures stay readable.
• ReceiptSchemaVersion — Both receipt versions the backend still emits. v2 is stamped on every live append; v1 survives for replay of events persisted before it (see packages/backend/src/operation-events/reconstruction.ts). A version outside this set is still refused: an unreadable outcome is an unknown one.
• RepoExploreSort — repo.explore’s sort vocabulary, named once. Spelled out in three places otherwise (both Protocols and both iterators), where a divergence would be a Literal that silently accepts less than the generated method does.
• RepoListSort — repo.list / repo.listPage’s shared sort vocabulary.
• RepositoryCheckpointStatus — Every terminal and in-progress repository checkpoint status.
• RepositoryCheckpointVerificationErrorReason — Stable failure categories produced by offline checkpoint verification.
• RepositoryExportErrorReason — Stable failure categories produced by export reading and verification.
• RepositoryExportMode — heads exports current versions; ops exports the operation history.
• RepositoryExportRow — One validated export row.
• SearchMode — text is BM25, vector is semantic, hybrid combines them.
• ShapeChangeCompatibilityResult — Compatibility response returned by shape-change endpoints.
• ShapeFields — A shape’s data.fields — the declaration side of shape validation.
• StreamAppendResult — Successful or rejected low-level stream append result.
• ThingKind — The record kinds a read projects. collection is absent: a collection reads as a thing and declares itself through collections.
• ThingKindFilter — What a filter may ASK for. Wider than what a read projects for the deprecation window: collection narrows to things the certificate closure calls collections, while assertion narrows to rows with an assertion target. Neither alias is projected as a record kind.
• Unset — Annotate optional parameters as int | Unset, defaulting to UNSET.
• WhereOp — Comparison operators accepted by a where predicate.
• WhereScalar — Routeable scalar RHS. Mirrors WhereScalarRhs in the TypeScript SDK.

Constants

• CONTENT_FIELD_LIMIT_ERROR — Corrective error text for a content field that exceeds the byte limit.
• DEFAULT_API_URL — Mirrors DEFAULT_API_URL in the TypeScript SDK.
• DEPENDENCY_FAILED — The per-operation code of an operation that failed only because an operation it depends on failed.
• KNOWN_CHECKPOINT_CONTENT_TYPES — Checkpoint access media types recognized by this SDK build.
• KNOWN_COMPONENT_INSTALL_RESULT_STATES — Component install health states recognized by this SDK build.
• KNOWN_COMPONENT_SUMMARY_STATES — Component installation lifecycle states recognized by this SDK build.
• KNOWN_CREDENTIAL_SCOPES — Credential scoping levels recognized by this SDK build.
• KNOWN_GLOBAL_SEARCH_RESULT_ITEM_KINDS — Global search result kinds recognized by this SDK build.
• KNOWN_HOMEPAGE_FEATURED_ITEM_KINDS — Homepage featured item kinds recognized by this SDK build.
• KNOWN_ORG_AUTH_SCOPES — Org scopes this build knows, in TypeScript declaration order.
• KNOWN_ORG_MEMBER_STATUSES — Organization membership statuses recognized by this SDK build.
• KNOWN_ORG_ROLES — Organization membership roles recognized by this SDK build.
• KNOWN_REPO_AUTH_SCOPES — Repo scopes this build knows, in TypeScript declaration order.
• KNOWN_SUBSCRIBABLE_EVENT_TYPES — Subscription event types recognized by this SDK build.
• LEGACY_WREFS_REFUSAL — The message every request is refused with under legacy-wrefs.
• MAX_CONTENT_FIELD_BYTES — Maximum UTF-8 byte length accepted for a content field.
• SDK_VERSION — Read from installed package metadata, not a literal.
• UNSET — Sentinel meaning “this option was not provided”.
• __version__ — The installed distribution’s version, under the name packaging tools expect.