client.thing
Generated methods for the thing namespace.
Sync owner: WarmHubClient.thing. Async owner: AsyncWarmHubClient.thing.
Synchronous methods
Section titled “Synchronous methods”about(org_name: str, repo_name: str, wref: str, *, shape: str | Unset = UNSET, match: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, depth: float | Unset = UNSET, resolve_collections: bool | Unset = UNSET, role: Literal['from', 'to', 'ends'] | Unset = UNSET, limit: float | Unset = UNSET, cursor: str | Unset = UNSET, where: Sequence[Mapping[str, JsonValue]] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> AboutResultthing.about — query thing.about.
about_all
Section titled “about_all”about_all(org_name: str, repo_name: str, wref: str, *, max_items: int | Unset = UNSET, shape: JsonValue | Unset = UNSET, match: JsonValue | Unset = UNSET, include_retracted: JsonValue | Unset = UNSET, depth: JsonValue | Unset = UNSET, resolve_collections: JsonValue | Unset = UNSET, role: JsonValue | Unset = UNSET, limit: JsonValue | Unset = UNSET, cursor: str | Unset = UNSET, where: JsonValue | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Materialize every assertion about wref.
max_items carries the same observed-item semantics as
query_all.
about_iter
Section titled “about_iter”about_iter(org_name: str, repo_name: str, wref: str, *, shape: JsonValue | Unset = UNSET, match: JsonValue | Unset = UNSET, include_retracted: JsonValue | Unset = UNSET, depth: JsonValue | Unset = UNSET, resolve_collections: JsonValue | Unset = UNSET, role: JsonValue | Unset = UNSET, limit: JsonValue | Unset = UNSET, cursor: str | Unset = UNSET, where: JsonValue | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Every assertion about wref, page by page. for a in ....
A plain generator-backed iterator: there is nothing to await here, which is the one shape difference from the async twin.
The page field is assertions, not items — per-method, from the
TypeScript body the manifest records. Assuming items would yield
nothing and look like an empty result.
count(org_name: str, repo_name: str, *, shape: str | Unset = UNSET, about: str | Unset = UNSET, affirmed_about: str | Unset = UNSET, kind: ThingKind | Unset = UNSET, match: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, resolve_collections: bool | Unset = UNSET, component_ref: str | Unset = UNSET, exclude_components: bool | Unset = UNSET, exclude_infra_shapes: bool | Unset = UNSET, where: Sequence[WherePredicate] | Unset = UNSET, since_repo_seq: int | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)The async twin’s docstring applies verbatim: see
AsyncThingFilterMixin.count.
get(org_name: str, repo_name: str, wref: str, version: float | Unset = UNSET, *, include_retracted: bool | Unset = UNSET, data_mode: Literal['auto', 'full'] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> WireThingDetailthing.get — query thing.get.
get_many
Section titled “get_many”get_many(org_name: str | None, repo_name: str | None, wrefs: Sequence[str], version: int | Unset = UNSET, *, include_retracted: bool | Unset = UNSET, data_mode: DataMode | Unset = UNSET, chunk_size: int | Unset = UNSET, chunk_concurrency: int | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)See AsyncThingBatchMixin.get_many in thing_batch.
chunk_concurrency is validated and then ignored here; chunks run
sequentially. See the module docstring.
get_with_lease
Section titled “get_with_lease”get_with_lease(org_name: str, repo_name: str, wref: str, *, ttl_ms: float | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> ThingGetWithLeasething.getWithLease — mutate thing.getWithLease.
graph(org_name: str, repo_name: str, wref: str, *, version: float | Unset = UNSET, depth: float | Unset = UNSET, limit: float | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> ThingGraphResultthing.graph — query thing.graph.
head_changes
Section titled “head_changes”head_changes(org_name: str, repo_name: str, *, since_repo_seq: int, limit: int | Unset = UNSET, shape: str | Unset = UNSET, kind: ThingKind | Unset = UNSET, match: str | Unset = UNSET, data_mode: DataMode | Unset = UNSET, component_ref: str | Unset = UNSET, exclude_components: bool | Unset = UNSET, exclude_infra_shapes: bool | Unset = UNSET, where: Sequence[WherePredicate] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)See AsyncThingChangesMixin.head_changes.
head_versions
Section titled “head_versions”head_versions(org_name: str | None, repo_name: str | None, wrefs: Sequence[str], *, chunk_size: int | Unset = UNSET, chunk_concurrency: int | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)See AsyncThingBatchMixin.head_versions in thing_batch.
chunk_concurrency is validated and then ignored here; chunks run
sequentially. See the module docstring.
history
Section titled “history”history(org_name: str, repo_name: str, *, wref: str | Unset = UNSET, shape: str | Unset = UNSET, about: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, resolve_collections: bool | Unset = UNSET, match: str | Unset = UNSET, limit: float | Unset = UNSET, cursor: str | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> HistoryResultthing.history — query thing.history.
history_iter
Section titled “history_iter”history_iter(org_name: str, repo_name: str, *, wref: str | Unset = UNSET, shape: str | Unset = UNSET, about: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, resolve_collections: bool | Unset = UNSET, match: str | Unset = UNSET, limit: float | Unset = UNSET, cursor: str | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Every version in a thing history, page by page.
Provide at least one selector — a concrete wref, a shape
filter, or an about target. The page field is versions, not
items.
query(org_name: str, repo_name: str, *, shape: str | Unset = UNSET, about: str | Unset = UNSET, affirmed_about: str | Unset = UNSET, kind: ThingKind | Unset = UNSET, match: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, resolve_collections: bool | Unset = UNSET, role: CollectionRole | Unset = UNSET, limit: int | Unset = UNSET, cursor: str | Unset = UNSET, component_ref: str | Unset = UNSET, exclude_components: bool | Unset = UNSET, exclude_infra_shapes: bool | Unset = UNSET, where: Sequence[WherePredicate] | Unset = UNSET, since_repo_seq: int | Unset = UNSET, decode_as: type[PayloadT] | Unset = UNSET, decoder: PayloadDecoder[PayloadT] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)The async twin’s docstring applies verbatim: see
AsyncThingFilterMixin.query.
query_all
Section titled “query_all”query_all(org_name: str, repo_name: str, *, max_items: int | Unset = UNSET, shape: str | Unset = UNSET, about: str | Unset = UNSET, affirmed_about: str | Unset = UNSET, kind: ThingKind | Unset = UNSET, match: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, resolve_collections: bool | Unset = UNSET, role: CollectionRole | Unset = UNSET, limit: int | Unset = UNSET, cursor: str | Unset = UNSET, component_ref: str | Unset = UNSET, exclude_components: bool | Unset = UNSET, exclude_infra_shapes: bool | Unset = UNSET, where: Sequence[WherePredicate] | Unset = UNSET, decode_as: type[PayloadT] | Unset = UNSET, decoder: PayloadDecoder[PayloadT] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)See AsyncThingPaginationMixin.query_all in thing_pagination.
query_changes
Section titled “query_changes”query_changes(org_name: str, repo_name: str, *, since_repo_seq: int, limit: int | Unset = UNSET, shape: str | Unset = UNSET, about: str | Unset = UNSET, kind: ThingKind | Unset = UNSET, match: str | Unset = UNSET, resolve_collections: bool | Unset = UNSET, role: CollectionRole | Unset = UNSET, component_ref: str | Unset = UNSET, exclude_components: bool | Unset = UNSET, exclude_infra_shapes: bool | Unset = UNSET, where: Sequence[WherePredicate] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)See AsyncThingChangesMixin.query_changes.
query_iter
Section titled “query_iter”query_iter(org_name: str, repo_name: str, *, shape: str | Unset = UNSET, about: str | Unset = UNSET, affirmed_about: str | Unset = UNSET, kind: ThingKind | Unset = UNSET, match: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, resolve_collections: bool | Unset = UNSET, role: CollectionRole | Unset = UNSET, limit: int | Unset = UNSET, cursor: str | Unset = UNSET, component_ref: str | Unset = UNSET, exclude_components: bool | Unset = UNSET, exclude_infra_shapes: bool | Unset = UNSET, where: Sequence[WherePredicate] | Unset = UNSET, decode_as: type[PayloadT] | Unset = UNSET, decoder: PayloadDecoder[PayloadT] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)See AsyncThingPaginationMixin.query_iter in thing_pagination.
refs(org_name: str, repo_name: str, wref: str, *, direction: Literal['inbound', 'outbound'] | Unset = UNSET, field_path: str | Unset = UNSET, limit: float | Unset = UNSET, cursor: str | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> RefsResultthing.refs — query thing.refs.
refs_all
Section titled “refs_all”refs_all(org_name: str, repo_name: str, wref: str, *, max_items: int | Unset = UNSET, direction: JsonValue | Unset = UNSET, field_path: JsonValue | Unset = UNSET, limit: JsonValue | Unset = UNSET, cursor: str | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Materialize every reference to wref.
max_items carries the same observed-item semantics as
AsyncThingPaginationMixin.query_all and head_all.
refs_iter
Section titled “refs_iter”refs_iter(org_name: str, repo_name: str, wref: str, *, direction: JsonValue | Unset = UNSET, field_path: JsonValue | Unset = UNSET, limit: JsonValue | Unset = UNSET, cursor: str | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Every reference to wref, page by page. for item in ....
A plain generator-backed iterator. The async twin returns an
AsyncIterator from a deliberately non-async factory; here there is
nothing to await, so that question does not arise.
No decode_as/decoder: refs returns reference stubs, not
records, so there is no caller payload to decode. Accepting the
parameters and ignoring them would be worse than not having them.
release_lease
Section titled “release_lease”release_lease(org_name: str, repo_name: str, wref: str, lease_id: str, *, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> Nonething.releaseLease — mutate thing.releaseLease.
rename
Section titled “rename”rename(org_name: str, repo_name: str, shape_name: str, old_name: str, new_name: str, *, event_request_id: str, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> RenameCompatibilityResult0 | RenameCompatibilityResult1thing.rename — mutate thing.rename.
resolve
Section titled “resolve”resolve(org_name: str, repo_name: str, wref: str, *, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> WireThingDetailthing.resolve — query thing.resolve.
search
Section titled “search”search(org_name: str, repo_name: str, query: str, *, shape: str | Unset = UNSET, about: str | Unset = UNSET, affirmed_about: str | Unset = UNSET, kind: ThingKind | Unset = UNSET, match: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, resolve_collections: bool | Unset = UNSET, limit: int | Unset = UNSET, cursor: str | Unset = UNSET, component_ref: str | Unset = UNSET, exclude_components: bool | Unset = UNSET, exclude_infra_shapes: bool | Unset = UNSET, mode: SearchMode | Unset = UNSET, name_match: NameMatch | Unset = UNSET, decode_as: type[PayloadT] | Unset = UNSET, decoder: PayloadDecoder[PayloadT] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)The async twin’s docstring applies verbatim: see
AsyncThingFilterMixin.search.
search_iter
Section titled “search_iter”search_iter(org_name: str, repo_name: str, query: str, *, shape: str | Unset = UNSET, about: str | Unset = UNSET, kind: ThingKind | Unset = UNSET, match: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, resolve_collections: bool | Unset = UNSET, limit: int | Unset = UNSET, cursor: str | Unset = UNSET, component_ref: str | Unset = UNSET, exclude_components: bool | Unset = UNSET, exclude_infra_shapes: bool | Unset = UNSET, mode: SearchMode | Unset = UNSET, name_match: NameMatch | Unset = UNSET, decode_as: type[PayloadT] | Unset = UNSET, decoder: PayloadDecoder[PayloadT] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Every ranked search hit, page by page. for item in ....
The decoder is resolved here rather than inside the page fetch, so a
bad decode_as fails on the call that named it.
When about is set or resolve_collections is true, pages may be
sparse. Iterating to exhaustion is the right way to read those; a page
with no visible rows is not the end of the results.
Asynchronous methods
Section titled “Asynchronous methods”about(org_name: str, repo_name: str, wref: str, *, shape: str | Unset = UNSET, match: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, depth: float | Unset = UNSET, resolve_collections: bool | Unset = UNSET, role: Literal['from', 'to', 'ends'] | Unset = UNSET, limit: float | Unset = UNSET, cursor: str | Unset = UNSET, where: Sequence[Mapping[str, JsonValue]] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> AboutResultthing.about — query thing.about.
about_all
Section titled “about_all”about_all(org_name: str, repo_name: str, wref: str, *, max_items: int | Unset = UNSET, shape: JsonValue | Unset = UNSET, match: JsonValue | Unset = UNSET, include_retracted: JsonValue | Unset = UNSET, depth: JsonValue | Unset = UNSET, resolve_collections: JsonValue | Unset = UNSET, role: JsonValue | Unset = UNSET, limit: JsonValue | Unset = UNSET, cursor: str | Unset = UNSET, where: JsonValue | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Materialize every assertion about wref.
max_items carries the same observed-item semantics as
query_all and AsyncThingNamespace.head_all.
about_iter
Section titled “about_iter”about_iter(org_name: str, repo_name: str, wref: str, *, shape: JsonValue | Unset = UNSET, match: JsonValue | Unset = UNSET, include_retracted: JsonValue | Unset = UNSET, depth: JsonValue | Unset = UNSET, resolve_collections: JsonValue | Unset = UNSET, role: JsonValue | Unset = UNSET, limit: JsonValue | Unset = UNSET, cursor: str | Unset = UNSET, where: JsonValue | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Every assertion about wref, page by page. async for a in ....
A non-async factory returning an async iterator, for the reason given on
query_iter.
The page field is assertions, not items. It is per-method and it
comes from the TypeScript body the manifest records; assuming items
would yield nothing and look like an empty result.
count(org_name: str, repo_name: str, *, shape: str | Unset = UNSET, about: str | Unset = UNSET, affirmed_about: str | Unset = UNSET, kind: ThingKind | Unset = UNSET, match: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, resolve_collections: bool | Unset = UNSET, component_ref: str | Unset = UNSET, exclude_components: bool | Unset = UNSET, exclude_infra_shapes: bool | Unset = UNSET, where: Sequence[WherePredicate] | Unset = UNSET, since_repo_seq: int | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)How many records match, without returning any of them.
Takes the same filters as query except role, and no
pagination — the reference ignores limit and cursor here, so
they are not offered.
get(org_name: str, repo_name: str, wref: str, version: float | Unset = UNSET, *, include_retracted: bool | Unset = UNSET, data_mode: Literal['auto', 'full'] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> WireThingDetailthing.get — query thing.get.
get_many
Section titled “get_many”get_many(org_name: str | None, repo_name: str | None, wrefs: Sequence[str], version: int | Unset = UNSET, *, include_retracted: bool | Unset = UNSET, data_mode: DataMode | Unset = UNSET, chunk_size: int | Unset = UNSET, chunk_concurrency: int | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Read many records by wref in one call, auto-chunked.
An empty wrefs returns an empty result and issues no request.
A wref the caller cannot see, or that does not exist, comes back in
missing rather than raising. Check it — len(items) is not
len(wrefs) in general, and duplicates in wrefs are preserved.
chunk_size is clamped to [1, 500], the backend’s transport cap.
chunk_concurrency is clamped to [1, 8] and is honoured here;
the sync twin ignores it.
get_with_lease
Section titled “get_with_lease”get_with_lease(org_name: str, repo_name: str, wref: str, *, ttl_ms: float | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> ThingGetWithLeasething.getWithLease — mutate thing.getWithLease.
graph(org_name: str, repo_name: str, wref: str, *, version: float | Unset = UNSET, depth: float | Unset = UNSET, limit: float | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> ThingGraphResultthing.graph — query thing.graph.
head_changes
Section titled “head_changes”head_changes(org_name: str, repo_name: str, *, since_repo_seq: int, limit: int | Unset = UNSET, shape: str | Unset = UNSET, kind: ThingKind | Unset = UNSET, match: str | Unset = UNSET, data_mode: DataMode | Unset = UNSET, component_ref: str | Unset = UNSET, exclude_components: bool | Unset = UNSET, exclude_infra_shapes: bool | Unset = UNSET, where: Sequence[WherePredicate] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Every head change after since_repo_seq, plus the checkpoint.
since_repo_seq is a STRICT lower bound; -1 seeds a complete
snapshot. Retracted rows are included — an identity rename carries its
checkpoint wref, a retraction carries active=False — and the scan
returns only after draining the terminal page.
This is not, by itself, a complete local-mirror protocol: it does not fan out changes caused by another identity. It is the resumable half.
Raises VALIDATION_ERROR if the terminal page carries no
repoSeq; nothing partial is returned in that case.
head_versions
Section titled “head_versions”head_versions(org_name: str | None, repo_name: str | None, wrefs: Sequence[str], *, chunk_size: int | Unset = UNSET, chunk_concurrency: int | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Cheap per-wref freshness probe. No payload comes back.
A locally cached copy is stale when durable_id differs, when
version or active differ, or when the wref is in missing.
Use this instead of get_many when the answer is “did anything
change”, because it does not transfer data.
history
Section titled “history”history(org_name: str, repo_name: str, *, wref: str | Unset = UNSET, shape: str | Unset = UNSET, about: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, resolve_collections: bool | Unset = UNSET, match: str | Unset = UNSET, limit: float | Unset = UNSET, cursor: str | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> HistoryResultthing.history — query thing.history.
history_iter
Section titled “history_iter”history_iter(org_name: str, repo_name: str, *, wref: str | Unset = UNSET, shape: str | Unset = UNSET, about: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, resolve_collections: bool | Unset = UNSET, match: str | Unset = UNSET, limit: float | Unset = UNSET, cursor: str | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Every version in a thing history, page by page.
Provide at least one selector — a concrete wref, a shape
filter, or an about target. The page field is versions, not
items.
query(org_name: str, repo_name: str, *, shape: str | Unset = UNSET, about: str | Unset = UNSET, affirmed_about: str | Unset = UNSET, kind: ThingKind | Unset = UNSET, match: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, resolve_collections: bool | Unset = UNSET, role: CollectionRole | Unset = UNSET, limit: int | Unset = UNSET, cursor: str | Unset = UNSET, component_ref: str | Unset = UNSET, exclude_components: bool | Unset = UNSET, exclude_infra_shapes: bool | Unset = UNSET, where: Sequence[WherePredicate] | Unset = UNSET, since_repo_seq: int | Unset = UNSET, decode_as: type[PayloadT] | Unset = UNSET, decoder: PayloadDecoder[PayloadT] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)One page of records matching the supplied filters.
The assertion-traversal read. about narrows to assertions about a
target wref; resolve_collections expands collection targets to
their members, and role then keeps only the members occupying that
end of the relationship.
Returns the same page shape as AsyncThingNamespace.head, so
decode_as and decoder work identically here.
Cursor contract: a cursor is a short-lived resume token for the same
query and result scope. If filters, visibility, or backing streams
change, the backend may reject it with VALIDATION_ERROR / “Invalid
cursor” — restart without cursor rather than retrying the stale
token.
query_all
Section titled “query_all”query_all(org_name: str, repo_name: str, *, max_items: int | Unset = UNSET, shape: str | Unset = UNSET, about: str | Unset = UNSET, affirmed_about: str | Unset = UNSET, kind: ThingKind | Unset = UNSET, match: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, resolve_collections: bool | Unset = UNSET, role: CollectionRole | Unset = UNSET, limit: int | Unset = UNSET, cursor: str | Unset = UNSET, component_ref: str | Unset = UNSET, exclude_components: bool | Unset = UNSET, exclude_infra_shapes: bool | Unset = UNSET, where: Sequence[WherePredicate] | Unset = UNSET, decode_as: type[PayloadT] | Unset = UNSET, decoder: PayloadDecoder[PayloadT] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Materialize every matching record.
max_items — TypeScript’s max, renamed because the mechanical
answer shadows a builtin (design.md, Pagination) — raises
VALIDATION_ERROR once more than that many items have actually
been observed. It is an observed-item count, not a page-count or a
cursor heuristic: sparse-paged surfaces return a nextCursor with no
further visible rows, so nothing else is sound.
query_changes
Section titled “query_changes”query_changes(org_name: str, repo_name: str, *, since_repo_seq: int, limit: int | Unset = UNSET, shape: str | Unset = UNSET, about: str | Unset = UNSET, kind: ThingKind | Unset = UNSET, match: str | Unset = UNSET, resolve_collections: bool | Unset = UNSET, role: CollectionRole | Unset = UNSET, component_ref: str | Unset = UNSET, exclude_components: bool | Unset = UNSET, exclude_infra_shapes: bool | Unset = UNSET, where: Sequence[WherePredicate] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Every filtered change after since_repo_seq, plus the checkpoint.
head_changes narrowed by the assertion-traversal filters —
about, resolve_collections and role. Same checkpoint
contract, same forced retractions, same required lower bound.
query_iter
Section titled “query_iter”query_iter(org_name: str, repo_name: str, *, shape: str | Unset = UNSET, about: str | Unset = UNSET, affirmed_about: str | Unset = UNSET, kind: ThingKind | Unset = UNSET, match: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, resolve_collections: bool | Unset = UNSET, role: CollectionRole | Unset = UNSET, limit: int | Unset = UNSET, cursor: str | Unset = UNSET, component_ref: str | Unset = UNSET, exclude_components: bool | Unset = UNSET, exclude_infra_shapes: bool | Unset = UNSET, where: Sequence[WherePredicate] | Unset = UNSET, decode_as: type[PayloadT] | Unset = UNSET, decoder: PayloadDecoder[PayloadT] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Every matching record, page by page. async for item in ....
A non-async factory returning an async iterator, deliberately: an
async def would return a coroutine, and async for iterates the
expression rather than awaiting it first, so the async-function form
fails at runtime. Same rule as head_iter and watch.
cursor resumes from a saved token; the iterator advances it after
the first request. The cursor-advance guard runs on every page.
The decoder is resolved here rather than inside the page fetch, so a
bad decode_as fails on the call that named it instead of on
whichever page a caller happens to pull first.
refs(org_name: str, repo_name: str, wref: str, *, direction: Literal['inbound', 'outbound'] | Unset = UNSET, field_path: str | Unset = UNSET, limit: float | Unset = UNSET, cursor: str | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> RefsResultthing.refs — query thing.refs.
refs_all
Section titled “refs_all”refs_all(org_name: str, repo_name: str, wref: str, *, max_items: int | Unset = UNSET, direction: JsonValue | Unset = UNSET, field_path: JsonValue | Unset = UNSET, limit: JsonValue | Unset = UNSET, cursor: str | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Materialize every reference to wref.
max_items carries the same observed-item semantics as
query_all and AsyncThingNamespace.head_all.
refs_iter
Section titled “refs_iter”refs_iter(org_name: str, repo_name: str, wref: str, *, direction: JsonValue | Unset = UNSET, field_path: JsonValue | Unset = UNSET, limit: JsonValue | Unset = UNSET, cursor: str | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Every reference to wref, page by page. async for item in ....
A non-async factory returning an async iterator, for the reason given on
query_iter.
No decode_as/decoder: refs returns reference stubs, not
records, so there is no caller payload to decode. Accepting the
parameters and ignoring them would be worse than not having them.
release_lease
Section titled “release_lease”release_lease(org_name: str, repo_name: str, wref: str, lease_id: str, *, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> Nonething.releaseLease — mutate thing.releaseLease.
rename
Section titled “rename”rename(org_name: str, repo_name: str, shape_name: str, old_name: str, new_name: str, *, event_request_id: str, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> RenameCompatibilityResult0 | RenameCompatibilityResult1thing.rename — mutate thing.rename.
resolve
Section titled “resolve”resolve(org_name: str, repo_name: str, wref: str, *, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET) -> WireThingDetailthing.resolve — query thing.resolve.
search
Section titled “search”search(org_name: str, repo_name: str, query: str, *, shape: str | Unset = UNSET, about: str | Unset = UNSET, affirmed_about: str | Unset = UNSET, kind: ThingKind | Unset = UNSET, match: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, resolve_collections: bool | Unset = UNSET, limit: int | Unset = UNSET, cursor: str | Unset = UNSET, component_ref: str | Unset = UNSET, exclude_components: bool | Unset = UNSET, exclude_infra_shapes: bool | Unset = UNSET, mode: SearchMode | Unset = UNSET, name_match: NameMatch | Unset = UNSET, decode_as: type[PayloadT] | Unset = UNSET, decoder: PayloadDecoder[PayloadT] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)One page of full-text search results.
mode selects BM25 (text, the default), semantic (vector) or
both (hybrid). name_match="deterministic" opts into literal name
matching before ranked search, which is what a UI list filter wants.
No where: search has no field-value predicates in v1. Use
query for typed structured filtering.
When about is set or resolve_collections is true, pages may be
sparse — keep paginating until next_cursor is absent.
search_iter
Section titled “search_iter”search_iter(org_name: str, repo_name: str, query: str, *, shape: str | Unset = UNSET, about: str | Unset = UNSET, kind: ThingKind | Unset = UNSET, match: str | Unset = UNSET, include_retracted: bool | Unset = UNSET, resolve_collections: bool | Unset = UNSET, limit: int | Unset = UNSET, cursor: str | Unset = UNSET, component_ref: str | Unset = UNSET, exclude_components: bool | Unset = UNSET, exclude_infra_shapes: bool | Unset = UNSET, mode: SearchMode | Unset = UNSET, name_match: NameMatch | Unset = UNSET, decode_as: type[PayloadT] | Unset = UNSET, decoder: PayloadDecoder[PayloadT] | Unset = UNSET, extra_headers: ExtraHeaders | Unset = UNSET, extra_query: ExtraQuery | Unset = UNSET, extra_body: ExtraBody | Unset = UNSET)Every ranked search hit, page by page. async for item in ....
The decoder is resolved here rather than inside the page fetch, so a
bad decode_as fails on the call that named it instead of on
whichever page a caller happens to pull first — the same rule
query_iter follows.
When about is set or resolve_collections is true, pages may be
sparse. Iterating to exhaustion is the right way to read those; a page
with no visible rows is not the end of the results.