Hubuum client library (Python)

Documentation · Hubuum ecosystem

hubuum-client is a modern, fully typed Python client for the Hubuum asset-management API. It provides matching synchronous and asynchronous clients, Pydantic v2 models, typed resource IDs, immutable queries, cursor pagination, structured errors, and a contract-checked interface for all 227 operations in the server's OpenAPI surface.

Version 0.0.10 targets Hubuum server v0.0.17. Compatibility is tested against the tag-and-digest server image recorded in the compatibility matrix, including repeated full restores and JSON-null recovery in both runtimes.

Schema revisions, impact diagnostics, retained HTML repair reports, and task cancellation have matching typed sync/async APIs. See the schema workflow and upgrade notes.

Credential management now requires single-use password approval, including token creation/renewal, user passwords, credential-bearing imports, and restore confirmation. Task discovery supports resource, lifecycle, and retained-option filters for all six task kinds.

Installation

python -m pip install hubuum-client

Python 3.11 or newer is required. The runtime dependencies are only HTTPX and Pydantic.

Quick start

from hubuum_client import ClassCreate, Client, Credentials, Query

with Client("https://hubuum.example.com") as client:
    client.login(Credentials("alice", "correct-horse-battery-staple"))

    classes = client.classes.list(Query().where("name", "server").limit(25).include_total())

    created = client.classes.create(
        ClassCreate(
            name="server",
            collection_id=1,
            description="Server inventory",
        )
    )
    print(created.id, len(classes))

The asynchronous API has the same shape:

import asyncio

from hubuum_client import AsyncClient, Credentials, Query


async def main() -> None:
    async with AsyncClient("https://hubuum.example.com") as client:
        await client.login(Credentials("alice", "secret"))
        page = await client.classes.by_name("Servers").objects.page(
            Query().where("name", "web-01").include_total()
        )
        print(page.total_count, page.items)


asyncio.run(main())

Context-managed clients remain open for the entire block and reuse their HTTP connection pools. Applications that manage startup and shutdown explicitly can keep the same client for their full lifetime:

client = Client("https://hubuum.example.com")
try:
    client.login(Credentials("alice", "secret"))
    run_application(client)
finally:
    client.close()

The async equivalent uses await client.close(). Reuse a client instead of constructing one per request so eligible TCP/TLS connections can be reused; see Client setup for synchronous and asynchronous lifetime examples.

Credentials and bearer tokens have redacted representations. TLS certificate validation is enabled by default; disabling it is an explicit client option and should be limited to disposable development systems.

Hubuum v0.0.17 reports the authoritative expiry for newly issued tokens. After login or token minting, it is available as client.token.expires_at or created_token.expires_at. The unauthenticated public configuration reports the default and maximum accepted lifetimes:

config = client.config()
default_hours = config.authentication.default_token_lifetime_hours
max_hours = config.authentication.max_token_lifetime_hours

Resource services

The typed surface currently covers the most common Hubuum workflows:

• collections, hierarchy traversal, and parent moves;
• classes and class-scoped objects, including exact-name addressing and nested data filtering and atomic JSON Patch;
• users, groups, memberships, and user anonymization;
• lifecycle-aware scoped token listing, point lookup, minting, renewal, and revocation;
• class relations and object relations;
• typed grouped and multi-measure object aggregates;
• cursor pagination, typed task events, and bounded task polling;
• typed import graphs/results and export requests/JSON or rendered output;
• health, readiness, Prometheus metrics, and public server configuration.

Structured JSON and SSE search are available through openapi.call() and openapi.stream(..., json=...); see advanced usage. The upgrade notes cover the required maintenance window, notification migration, and format 7 backups.

Every v0.0.17 OpenAPI operation is registered by its stable operationId:

from hubuum_client import OpenAPIOptions

result = client.openapi.call(
    "getApiV1Search",
    options=OpenAPIOptions(params={"q": "server", "limit_per_kind": 10}),
)

The checked-in manifest covers all 227 methods, paths, path variables, body media types, public/authenticated policies, JSON responses, rendered text exports, and the search event stream. request() remains available for server extensions outside the pinned specification. Both interfaces are constrained to the configured origin.

Querying and pagination

Queries are immutable and reusable:

from hubuum_client import FilterOperator, Query

base = Query().where("name", "server", FilterOperator.ICONTAINS)
first_page = client.classes.page(base.limit(25).include_total())
all_matches = client.classes.all(base, max_items=5_000)

active_web_servers = client.classes.by_name("Servers").objects.all(
    Query().data("status").equals("active").data("tags").contains_all("web", "api")
)

Page exposes items, next_cursor, total_count, and the effective page_limit. Automatic pagination detects repeated cursors and enforces page and item limits. The fluent data() selector supports nested paths, typed comparisons, arrays, nulls, object keys, and IP/network operators; see Queries and pagination.

Group membership uses the same typed, cursor-aware interface:

member_page = client.groups.members_page(group_id, Query().limit(25).include_total())
all_members = client.groups.all_members(group_id, max_items=5_000)

Documentation

• Client setup
• Queries and pagination
• API reference
• Compatibility policy
• Docker-backed end-to-end tests
• Changelog

Development

uv sync --extra dev
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run bandit -q -r src scripts
uv run zizmor .
uv run pytest --cov
uv run mkdocs build --strict

The full pinned-server workflow is:

./scripts/run-e2e-tests.sh

See AGENTS.md for repository conventions and the exact e2e stack. Contributions are welcome; see CONTRIBUTING.md for the development and pull-request workflow. Maintainers can find the release process in the release guide.

Please report security issues according to SECURITY.md, rather than in a public issue.

License

Distributed under the MIT License. See LICENSE.

Documentation-only CI

Pull requests and pushes containing only prose or documentation-site inputs run Markdown lint and documentation validation without the application test/build matrix. Unknown files, source changes, executable examples, and declared test/build inputs retain application CI. Mixed changes run both kinds of checks.

scripts/ci-policy.py owns the allowlist and exceptions. Update its regression tests whenever a document becomes a build, test, or packaging input; direct literal Rust includes are checked automatically. Run the policy tests with python3 scripts/test-ci-policy.py.

The Lint, types, docs, and package check is the aggregate CI gate: classification failures, failed checks, and unexpectedly skipped required jobs fail it. Keep that check required in branch protection. Add the ci:full pull-request label or dispatch the CI workflow manually to request complete validation. Release validation and separately scheduled checks retain their existing coverage.