Python SDK Reference

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

This build documents 266 root exports and 26 client namespace projections.

Client namespaces

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 a new shape, thing, assertion, or collection.
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).
GlobalSearchResult — Generated from GlobalSearchResult.
GlobalSearchResultItem — Generated from GlobalSearchResultItem.
HeadResult — One page of a list read.
HistoryResult — Generated from HistoryResult.
HomepageFeaturedListsResult — Generated from HomepageFeaturedListsResult.
IndexedFieldsReport — Generated from IndexedFieldsReport.
LeaseHeld — A live read lease blocks this mutation or acquire (#3625).
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.
OperationEventReceiptV1 — Generated from OperationEventReceiptV1.
OperationEventRepo — Repository identity embedded in an immutable operation-event receipt.
OperationWarnings — Everything a write succeeded despite, for one operation.
Org — Generated from Org.
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.
Rename — Rewrite a thing’s or shape’s name in place.
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.
Retract — Mark the target retracted in a new version.
RetryPolicy — Knobs for the write path’s transient first-chunk retry.
Revise — Replace the shape-validated data on an existing target.
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.
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).
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.

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_org_auth_scope — Is value one of the org scopes this build knows about?
is_known_repo_auth_scope — Is value one of the repo scopes this build knows about?
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.
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.
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 server should return.
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 four record kinds a filter may name.
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.
KNOWN_ORG_AUTH_SCOPES — Org scopes this build knows, in TypeScript declaration order.
KNOWN_REPO_AUTH_SCOPES — Repo scopes this build knows, in TypeScript declaration order.
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.