API reference¶

Blocking client for the Hubuum server API.

Use the client as a context manager so its connection pool is closed deterministically. request is the safe extension point for routes that do not yet have a dedicated service method.

_base_url = normalize_base_url(base_url)

_http = httpx.Client(
    base_url=self._base_url,
    timeout=client_options.timeout,
    verify=client_options.verify,
    transport=transport,
    headers={
        "User-Agent": client_options.user_agent
        or f"hubuum-client-python/{__version__}"
    },
)

_token = (
    AccessToken(token) if isinstance(token, str) else token
)

base_url

class_relations

classes

collections

credential_approvals

exports

groups

imports

is_authenticated

object_relations

openapi

tasks

token

tokens

users

__enter__()

__exit__(*_)

__init__(
    base_url, *, token=None, options=None, transport=None
)

_build_request(method, path, *, json, options)

_request_response(method, path, *, json=None, options=None)

_request_stream_response(
    method, path, *, json=None, options=None
)

_send_request(request, request_body, *, stream)

close()

config()

healthz()

login(credentials)

logout()

me()

metrics()

metrics_at(path)

readyz()

request(
    method: str,
    path: str,
    *,
    json: BaseModel
    | Mapping[str, Any]
    | list[Any]
    | None = None,
    response_model: type[T],
    options: RequestOptions | None = None,
) -> T

request(
    method: str,
    path: str,
    *,
    json: BaseModel
    | Mapping[str, Any]
    | list[Any]
    | None = None,
    response_model: None = None,
    options: RequestOptions | None = None,
) -> Any

request(
    method,
    path,
    *,
    json=None,
    response_model=None,
    options=None,
)

stream(method, path, *, json=None, options=None)

Async client with the same resource surface as :class:Client.

_base_url = normalize_base_url(base_url)

_http = httpx.AsyncClient(
    base_url=self._base_url,
    timeout=client_options.timeout,
    verify=client_options.verify,
    transport=transport,
    headers={
        "User-Agent": client_options.user_agent
        or f"hubuum-client-python/{__version__}"
    },
)

_token = (
    AccessToken(token) if isinstance(token, str) else token
)

base_url

class_relations

classes

collections

credential_approvals

exports

groups

imports

is_authenticated

object_relations

openapi

tasks

token

tokens

users

__aenter__()

__aexit__(*_)

__init__(
    base_url, *, token=None, options=None, transport=None
)

_build_request(method, path, *, json, options)

_request_response(method, path, *, json=None, options=None)

_request_stream_response(
    method, path, *, json=None, options=None
)

_send_request(request, request_body, *, stream)

close()

config()

healthz()

login(credentials)

logout()

me()

metrics()

metrics_at(path)

readyz()

request(
    method: str,
    path: str,
    *,
    json: BaseModel
    | Mapping[str, Any]
    | list[Any]
    | None = None,
    response_model: type[T],
    options: RequestOptions | None = None,
) -> T

request(
    method: str,
    path: str,
    *,
    json: BaseModel
    | Mapping[str, Any]
    | list[Any]
    | None = None,
    response_model: None = None,
    options: RequestOptions | None = None,
) -> Any

request(
    method,
    path,
    *,
    json=None,
    response_model=None,
    options=None,
)

stream(method, path, *, json=None, options=None)

Connection behavior shared by synchronous and asynchronous clients.

timeout = 30.0

user_agent = None

verify = True

__init__(timeout=30.0, verify=True, user_agent=None)

Transport controls for one origin-locked request.

authenticated = True

headers = field(default=None, repr=False)

params = field(default=None, repr=False)

__init__(params=None, headers=None, authenticated=True)

Path, query, header, and response controls for an OpenAPI operation.

accept = None

content_type = None

headers = field(default=None, repr=False)

params = field(default=None, repr=False)

path_params = None

__init__(
    path_params=None,
    params=None,
    headers=None,
    accept=None,
    content_type=None,
)

Bases: NamedTuple

method

operation_id

path

request_media_type

request_media_types

response_media_types

Invoke every operation in Hubuum v0.0.16 by its stable OpenAPI operationId.

_client = client

operation_ids

__init__(client)

call(operation_id, *, json=None, options=None)

operation(operation_id)

stream(operation_id, *, json=None, options=None)

Asynchronous operation-ID interface for the complete v0.0.16 contract.

_client = client

operation_ids

__init__(client)

call(operation_id, *, json=None, options=None)

operation(operation_id)

stream(operation_id, *, json=None, options=None)

A synchronous response body consumed inside Client.stream().

__slots__ = ('_response',)

_response = response

headers

status_code

__init__(response)

iter_bytes()

iter_lines()

iter_text()

An asynchronous response body consumed inside AsyncClient.stream().

__slots__ = ('_response',)

_response = response

headers

status_code

__init__(response)

iter_bytes()

iter_lines()

iter_text()

Inspect, paginate, and wait for asynchronous Hubuum tasks.

_client = client

_service = _CursorService[Task](
    client, collection_path="/api/v1/tasks", model=Task
)

__init__(client)

all(query=None, *, max_pages=100, max_items=10000)

all_events(
    task_id, query=None, *, max_pages=100, max_items=10000
)

cancel(task_id, payload=None)

event_pages(task_id, query=None, *, max_pages=100)

events(task_id, query=None)

events_page(task_id, query=None)

get(task_id)

list(query=None)

page(query=None)

pages(query=None, *, max_pages=100)

wait(task_id, *, timeout_seconds=300.0, poll_interval=0.5)

Inspect, paginate, and wait for asynchronous Hubuum tasks.

_client = client

_service = _AsyncCursorService[Task](
    client, collection_path="/api/v1/tasks", model=Task
)

__init__(client)

all(query=None, *, max_pages=100, max_items=10000)

all_events(
    task_id, query=None, *, max_pages=100, max_items=10000
)

cancel(task_id, payload=None)

event_pages(task_id, query=None, *, max_pages=100)

events(task_id, query=None)

events_page(task_id, query=None)

get(task_id)

list(query=None)

page(query=None)

pages(query=None, *, max_pages=100)

wait(task_id, *, timeout_seconds=300.0, poll_interval=0.5)

Submit imports and inspect their task and per-entity outcomes.

_client = client

__init__(client)

_results_service(task_id)

all_results(
    task_id, query=None, *, max_pages=100, max_items=10000
)

get(task_id)

result_pages(task_id, query=None, *, max_pages=100)

results(task_id, query=None)

results_page(task_id, query=None)

run(
    payload,
    *,
    idempotency_key=None,
    approval=None,
    timeout_seconds=300.0,
    poll_interval=0.5,
)

submit(payload, *, idempotency_key=None, approval=None)

Async import submission and per-entity outcome inspection.

_client = client

__init__(client)

_results_service(task_id)

all_results(
    task_id, query=None, *, max_pages=100, max_items=10000
)

get(task_id)

result_pages(task_id, query=None, *, max_pages=100)

results(task_id, query=None)

results_page(task_id, query=None)

run(
    payload,
    *,
    idempotency_key=None,
    approval=None,
    timeout_seconds=300.0,
    poll_interval=0.5,
)

submit(payload, *, idempotency_key=None, approval=None)

Submit exports and retrieve their typed or rendered output.

_client = client

__init__(client)

get(task_id)

output(task_id)

output_stream(task_id)

run(
    payload,
    *,
    idempotency_key=None,
    timeout_seconds=300.0,
    poll_interval=0.5,
)

submit(payload, *, idempotency_key=None)

Async export submission and typed or rendered output retrieval.

_client = client

__init__(client)

get(task_id)

output(task_id)

output_stream(task_id)

run(
    payload,
    *,
    idempotency_key=None,
    timeout_seconds=300.0,
    poll_interval=0.5,
)

submit(payload, *, idempotency_key=None)

Stage, inspect, and explicitly activate one class's schema revisions.

_base = f'/api/v1/classes/{_segment(class_id)}/schema'

_client = client

__init__(client, class_id)

abandon(revision)

activate(revision, payload)

cancel(task_id)

generate_report(task_id, payload)

get()

impact(revision)

objects(options=None, *, status=None)

report(task_id, *, download=False)

revalidate(revision)

revision(revision)

revisions(options=None)

stage(payload)

work(task_id)

Stage, inspect, and explicitly activate one class's schema revisions.

_base = f'/api/v1/classes/{_segment(class_id)}/schema'

_client = client

__init__(client, class_id)

abandon(revision)

activate(revision, payload)

cancel(task_id)

generate_report(task_id, payload)

get()

impact(revision)

objects(options=None, *, status=None)

report(task_id, *, download=False)

revalidate(revision)

revision(revision)

revisions(options=None)

stage(payload)

work(task_id)

Numeric continuation controls for schema revisions and object compliance.

Bases: RequestModel

Bases: RequestModel

Bases: StrEnum

Bases: RequestModel

Bases: HubuumModel

Bases: HubuumModel

Bases: HubuumModel

Bases: HubuumModel

Bases: HubuumModel

Bases: HubuumModel

Bases: HubuumModel

Bases: HubuumModel

Bases: HubuumModel

Bases: HubuumModel

Bases: RequestModel

Bases: RequestModel

Idempotent cancellation, optionally conditional on the current task status.

Bases: StrEnum

Conservative dispatch evidence; cancellation cannot undo a remote side effect.

Immutable query parameters for list endpoints.

Reusing a base query is safe because every fluent method returns a new value.

cursor_value = None

filters = ()

include_total_value = None

limit_value = None

sort_value = None

__init__(
    filters=(),
    limit_value=None,
    cursor_value=None,
    sort_value=None,
    include_total_value=None,
)

as_params()

cursor(value)

data(*path)

include_total(value=True)

limit(value)

sort(value)

where(field, value, operator=EQUALS)

One typed Hubuum resource filter.

field

operator

value

__init__(field, operator, value)

as_pair()

A nested object data path selected from an immutable query.

Each terminal method returns a new :class:Query, so another data() selection or any normal query control can be chained immediately.

_path_value

path

query

__init__(query, path)

__post_init__()

_list_value(values)

_operator(operator, negate)

_value_filter(operator, value, *, negate)

array_length(value, *, negate=False)

between(lower, upper, *, negate=False)

contains(value, *, negate=False)

contains_all(*values, negate=False)

contains_ip(value, *, negate=False)

contains_network(value, *, negate=False)

ends_with(value, *, negate=False)

equals(value, *, negate=False)

gt(value, *, negate=False)

gte(value, *, negate=False)

has_key(key, *, negate=False)

icontains(value, *, negate=False)

iends_with(value, *, negate=False)

iequals(value, *, negate=False)

inet_equals(value, *, negate=False)

is_null(*, negate=False)

istarts_with(value, *, negate=False)

like(value, *, negate=False)

lt(value, *, negate=False)

lte(value, *, negate=False)

one_of(*values, negate=False)

overlaps_network(value, *, negate=False)

regex(value, *, negate=False)

starts_with(value, *, negate=False)

within_network(value, *, negate=False)

Bases: StrEnum

Operators understood by Hubuum's field__operator=value syntax.

ALL = 'all'

ARRAY_LENGTH = 'array_length'

BETWEEN = 'between'

CONTAINS = 'contains'

CONTAINS_IP = 'contains_ip'

CONTAINS_NETWORK = 'contains_network'

ENDSWITH = 'endswith'

EQUALS = 'equals'

GT = 'gt'

GTE = 'gte'

HAS_KEY = 'has_key'

ICONTAINS = 'icontains'

IENDSWITH = 'iendswith'

IEQUALS = 'iequals'

IN = 'in'

INET_EQUALS = 'inet_equals'

ISTARTSWITH = 'istartswith'

IS_NULL = 'is_null'

LIKE = 'like'

LT = 'lt'

LTE = 'lte'

NOT_ALL = 'not_all'

NOT_ARRAY_LENGTH = 'not_array_length'

NOT_BETWEEN = 'not_between'

NOT_CONTAINS = 'not_contains'

NOT_CONTAINS_IP = 'not_contains_ip'

NOT_CONTAINS_NETWORK = 'not_contains_network'

NOT_ENDSWITH = 'not_endswith'

NOT_EQUALS = 'not_equals'

NOT_GT = 'not_gt'

NOT_GTE = 'not_gte'

NOT_HAS_KEY = 'not_has_key'

NOT_ICONTAINS = 'not_icontains'

NOT_IENDSWITH = 'not_iendswith'

NOT_IEQUALS = 'not_iequals'

NOT_IN = 'not_in'

NOT_INET_EQUALS = 'not_inet_equals'

NOT_ISTARTSWITH = 'not_istartswith'

NOT_IS_NULL = 'not_is_null'

NOT_LIKE = 'not_like'

NOT_LT = 'not_lt'

NOT_LTE = 'not_lte'

NOT_OVERLAPS_NETWORK = 'not_overlaps_network'

NOT_REGEX = 'not_regex'

NOT_STARTSWITH = 'not_startswith'

NOT_WITHIN_NETWORK = 'not_within_network'

OVERLAPS_NETWORK = 'overlaps_network'

REGEX = 'regex'

STARTSWITH = 'startswith'

WITHIN_NETWORK = 'within_network'

Bases: Sequence[T], Generic[T]

One cursor-paginated response page.

has_next

items

next_cursor = None

page_limit = None

total_count = None

__getitem__(index: int) -> T

__getitem__(index: slice) -> tuple[T, ...]

__getitem__(index)

__init__(
    items,
    next_cursor=None,
    total_count=None,
    page_limit=None,
)

__iter__()

__len__()

Bases: StrEnum

Retained-token lifecycle subset selected by token list operations.

ACTIVE = 'active'

ALL = 'all'

EXPIRED = 'expired'

REVOKED = 'revoked'

Bases: HubuumModel

Bases: HubuumModel

normalize_runtime_collection(value)

Bases: HubuumModel

Bases: RequestModel

One validated RFC 6902 operation relative to an object's data root.

payload()

Bases: HubuumModel

Bases: HubuumModel

Bases: HubuumModel

Bases: _UserBase

User metadata returned by collection endpoints.

Bases: _UserBase

Canonical revision-owned user returned by point mutations and reads.

Bases: GroupPoint

Group metadata returned by collection endpoints.

Bases: HubuumModel

Canonical revision-owned group returned by point mutations and reads.

Bases: HubuumModel

A class-to-class relation and its optional per-object cardinality limits.

Bases: HubuumModel

Bases: HubuumModel

Generic asynchronous task with typed progress, links, and details.

Bases: HubuumModel

One event in a task's cursor-paginated lifecycle history.

Bases: HubuumModel

Typed item counters reported by an asynchronous task.

Bases: HubuumModel

Kind-specific task metadata exposed by Hubuum v0.0.16.

Bases: RequestModel

Create a class relation, optionally bounding either object's relation count.

from_max_relations applies independently to each object in the source class; to_max_relations applies independently to each object in the destination class. Omit a limit for unlimited cardinality.

Bases: RequestModel

Versioned asynchronous import request for the complete Hubuum graph.

payload()

Bases: RequestModel

Complete import graph with typed core resources.

Identity and integration sections remain JSON-object sequences so the complete v0.0.16 graph is accepted without exposing unstable or secret-bearing integration configuration in representations. Core collection, class, object, relation, and collection-permission sections are fully typed.

total_items

Bases: RequestModel

One import-v2 write condition checked by the queued worker.

Bases: StrEnum

Per-item collision and revision behavior for Hubuum import v2.

Bases: RequestModel

Original UTC timestamps restored by an authorized import.

Hubuum v0.0.16 accepts timezone-free ISO 8601 values and interprets them as UTC. The update timestamp must not precede the creation timestamp.

validate_order()

Bases: HubuumModel

Outcome for one entity processed by an import task.

Terminal import task and its per-entity result rows.

failed

succeeded

Bases: RequestModel

Typed request submitted to Hubuum's asynchronous export endpoint.

Bases: RequestModel

Validated resource boundary for an export request.

Global collection, class, and relation scopes do not accept identifiers. objects_in_class requires only class_id; related_objects requires both identifiers.

validate_identifiers()

Bases: HubuumModel

Structured output returned for application/json exports.

Non-JSON export output and the media type selected by the server.

Bases: RequestModel

Token-mint request using Hubuum's nested scope wire field.

Bases: RequestModel

Optional expiry override for a renewed token.

Bases: RequestModel

Independent permission and resource boundaries for a newly minted token.

Bases: RequestModel

One collection, class, or object included in a token boundary.

Bases: PrincipalTokenPoint

Lifecycle-aware token metadata returned by retained-token lists.

Bases: _TokenMetadataBase

Canonical point-in-time token metadata without routine usage state.

Bases: HubuumModel

Revision-owned membership between a principal and a group.

Bases: HubuumModel

Principal details nested in a membership or current-user response.

Bases: _TokenMetadataBase

Metadata for the token authenticating the current request.

Bases: HubuumModel

Bases: HubuumModel

Public client-safe server configuration.

Bases: HubuumModel

Public authentication settings needed by API consumers.

Bases: HubuumModel

Effective pagination settings exposed by the server.

Bearer token and optional authoritative expiry with a redacted representation.

Bases: HubuumError

A non-successful Hubuum API response.

The access token and request body are intentionally never retained.

Bases: HubuumError

A request failed before a valid HTTP response was received.

Bases: HubuumError

The server returned a successful response with an unexpected body.

Bases: HubuumError

A task reached a terminal state that does not represent full success.

Only the task ID and status are retained. In particular, the server's task summary is excluded because it can contain details derived from submitted data.

Bases: APIError

A conditional mutation used a stale resource validator.

Obtain single-use password approval and inspect retained evidence.

_client = client

__init__(client)

create(payload)

get(approval_id)

Obtain single-use password approval and inspect retained evidence.

_client = client

__init__(client)

create(payload)

get(approval_id)

Bases: RequestModel

Authenticate the acting human for exactly one intended mutation.

model_validate_json(json_data, **kwargs)

Bases: HubuumModel

Transient approval; token expiry must be copied into the final mutation.