hubuum-client 0.0.1__tar.gz

hubuum_client-0.0.1/.github/dependabot.yml

@@ -0,0 +1,31 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Europe/Oslo
+    cooldown:
+      default-days: 7
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Europe/Oslo
+    cooldown:
+      default-days: 7
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+    open-pull-requests-limit: 5

hubuum_client-0.0.1/.github/pull_request_template.md

@@ -0,0 +1,23 @@
+## Summary
+
+<!-- What changed, and why? -->
+
+## User impact
+
+<!-- Describe public API, compatibility, security, or operational impact. -->
+
+## Validation
+
+- [ ] Ruff formatting and linting
+- [ ] mypy
+- [ ] Unit tests with coverage
+- [ ] Strict documentation build
+- [ ] Package build
+- [ ] Pinned-server e2e tests, when server behavior is affected
+
+## Checklist
+
+- [ ] Tests cover the change, including sync/async parity where relevant
+- [ ] Documentation is updated
+- [ ] `[Unreleased]` in `CHANGELOG.md` is updated for user-visible changes
+- [ ] No credentials, tokens, production data, or generated artifacts are included

hubuum_client-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,95 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: read
+
+env:
+  UV_FROZEN: "1"
+  HUBUUM_TARGET_SERVER_VERSION: "0.0.3"
+  HUBUUM_TARGET_SERVER_IMAGE: ghcr.io/hubuum/hubuum-server:v0.0.3@sha256:f1f57a991f69005ee81f24e77533e61f75b5586949d98cccf1c40fc4329eb186
+
+jobs:
+  quality:
+    name: Lint, types, docs, and package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+      - run: uv sync --extra dev
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run mypy
+      - run: uv run bandit -q -r src scripts
+      - run: uv run zizmor .
+      - run: uv run mkdocs build --strict
+      - run: uv build
+
+  test:
+    name: Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+      - run: uv sync --extra test
+      - run: uv run pytest --cov=hubuum_client
+
+  server-contract:
+    name: Hubuum v0.0.3 OpenAPI contract
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+      - run: python scripts/check-openapi-contract.py
+
+  e2e:
+    name: Pinned Hubuum v0.0.3 e2e
+    runs-on: ubuntu-latest
+    needs: [quality, test, server-contract]
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+      - uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build wheel and run pinned live-server suite
+        run: ./scripts/run-e2e-tests.sh
+        env:
+          HUBUUM_E2E_SERVER_IMAGE: ${{ env.HUBUUM_TARGET_SERVER_IMAGE }}

hubuum_client-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build release distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: false
+      - name: Verify release tag
+        if: github.ref_type == 'tag'
+        run: test "${GITHUB_REF_NAME}" = "v$(uv version --short)"
+      - name: Build distributions
+        run: uv build
+      - name: Validate distributions
+        run: uvx --from twine==6.2.0 twine check --strict dist/*
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'push' && vars.PYPI_PUBLISH_ENABLED == 'true'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hubuum-client
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

hubuum_client-0.0.1/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+htmlcov/
+site/

hubuum_client-0.0.1/.python-version

@@ -0,0 +1 @@
+3.11

hubuum_client-0.0.1/AGENTS.md

@@ -0,0 +1,86 @@
+# Repository Guidelines
+
+These instructions apply to the entire repository.
+
+## Sources of truth
+
+- `pyproject.toml` defines the package version, supported Python versions,
+  dependencies, and verification configuration.
+- `src/hubuum_client/_constants.py` defines the target Hubuum server version and
+  immutable test image. Keep those values synchronized with `README.md`,
+  `CHANGELOG.md`, `docs/compatibility.md`, the e2e script, and CI.
+- Hubuum server `v0.0.3` and its committed `docs/openapi.json` are the
+  authoritative API contract. Do not infer wire fields from Python naming
+  preferences when the contract says otherwise.
+- Maintain sync/async capability parity unless a runtime constraint is
+  documented explicitly.
+
+## Architecture
+
+- Put response and request types in `models.py`, small ID and secret values in
+  `types.py`, and immutable list controls in `query.py`.
+- Keep shared URL validation, decoding, and error mapping in `_transport.py`.
+- Synchronous HTTP behavior belongs in `client.py` and `services.py`; matching
+  asynchronous behavior belongs in `async_client.py` and `async_services.py`.
+- Typed resource services are the preferred public API. Keep `request()` as a
+  constrained extension point for authenticated relative routes.
+- Never retain or expose bearer tokens, passwords, authorization headers, or
+  secret-bearing request bodies in exceptions, representations, or logs.
+
+## Verification
+
+Run all non-container checks before considering a change complete:
+
+```bash
+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
+uv build
+```
+
+Focused tests are useful while iterating but do not replace the full unit suite.
+Every behavior change needs regression coverage for both sync and async paths
+when they could diverge.
+
+## Docker-backed end-to-end tests
+
+Run the complete live-server suite with:
+
+```bash
+./scripts/run-e2e-tests.sh
+```
+
+The wrapper starts PostgreSQL and the immutable Hubuum v0.0.3 server image,
+waits for readiness, obtains the generated administrator password, runs the
+tests under `tests/e2e`, and removes its containers and network. Docker and
+Podman are both supported.
+
+Useful environment variables:
+
+- `HUBUUM_E2E_SERVER_IMAGE`: server image override; compatibility evidence must
+  use the pinned default.
+- `HUBUUM_E2E_POSTGRES_IMAGE`: PostgreSQL image override.
+- `HUBUUM_E2E_BASE_URL` and `HUBUUM_E2E_ADMIN_PASSWORD`: run against a
+  caller-managed server instead of provisioning containers.
+- `HUBUUM_E2E_CONTAINER_RUNTIME`: select `docker` or `podman`.
+- `HUBUUM_E2E_KEEP=1`: retain resources for diagnosis.
+- `HUBUUM_E2E_TIMEOUT`: stack startup timeout in seconds.
+
+Live tests must use unique resource names, avoid assumptions about global IDs,
+and clean up resources when doing so does not hide the primary failure. Do not
+describe unit tests or an unpinned live run as v0.0.3 compatibility evidence.
+
+## Change discipline
+
+- Preserve unrelated user changes and keep the worktree scoped.
+- Add user-visible changes to `[Unreleased]` in `CHANGELOG.md`.
+- Update documentation when public behavior, requirements, compatibility, or
+  the e2e workflow changes.
+- Prefer clear, idiomatic Python and explicit types over clever abstractions.
+- Do not suppress Ruff or mypy broadly; fix the type or isolate a justified,
+  narrow exception.

hubuum_client-0.0.1/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and releases follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.1] - 2026-07-25
+
+### Added
+
+- Initial typed Python client targeting Hubuum server v0.0.3.
+- Synchronous and asynchronous clients with equivalent resource services.
+- Typed Pydantic models and distinct ID types for core Hubuum resources.
+- Collection, class, object, user, group, relation, and task workflows.
+- Immutable filtering, cursor pages, bounded automatic pagination, and task polling.
+- Structured transport, decoding, authentication, permission, not-found,
+  conflict, and rate-limit exceptions.
+- Redacted credentials and access tokens plus origin-locked raw requests.
+- Unit, typing, documentation, and Docker-backed e2e test infrastructure.
+- GitHub CI, dependency update automation, contribution guidance, and an
+  explicitly gated PyPI trusted-publishing workflow.
+- Added an immutable fluent interface for nested object `data` filtering,
+  covering scalar, range, array, object-key, null, and IP/network operators,
+  with pinned-server end-to-end coverage.
+- Added a contract-checked operation interface covering all 196 Hubuum v0.0.3
+  OpenAPI endpoints, including authenticated/public policy, JSON/text/binary
+  response decoding, and incremental SSE consumption.
+- Added the complete class/object `by-name` surface and validated atomic RFC
+  6902 object-data patch operations, covering the API workflows used by
+  `hubuum-import-miami`.
+- Added `classes.by_id(id)` as the numeric counterpart to `classes.by_name(name)`,
+  with synchronous and asynchronous class operations and nested `.objects`
+  access.
+
+### Changed
+
+- Raised the branch-aware unit coverage gate from 90% to 95% after adding
+  request-construction coverage for every pinned OpenAPI operation and focused
+  transport, streaming, decoding, pagination, and sync/async failure tests.
+- Strengthened pinned-server compatibility evidence with forced multi-page
+  cursor traversal, a complete async resource lifecycle, non-administrator
+  permission boundaries, and live `400`, `401`, `403`, `404`, and `409` error
+  mapping; the e2e wrapper now tests the built wheel in an isolated environment.
+- Changed PyPI trusted publishing to run from protected `v*` tag pushes, with a
+  manually approved GitHub environment and an exact package-version check.
+- Added an evidence-linked client/server compatibility matrix and identified
+  the pinned e2e server image by both its `v0.0.3` tag and immutable digest.
+- Updated every GitHub Action to its latest immutable release commit and
+  corrected invalid checkout and Python setup action versions; release artifact
+  validation now uses an explicit Twine version.
+- Disabled persisted checkout credentials and release-job caching, added a
+  dependency update cooldown, bounded contract downloads to HTTPS sources, and
+  added Bandit and zizmor security gates to CI.
+- Aligned synchronous and asynchronous task polling on the same
+  `timeout_seconds` keyword, validated polling and pagination bounds before
+  doing work, and prevented poll sleeps from exceeding the remaining timeout.
+- Fixed the end-to-end wrapper on Bash 3.2 when invoked without additional
+  pytest arguments.
+- Replaced long client and raw-request parameter lists with shared typed
+  `ClientOptions` and `RequestOptions` values and re-enabled Ruff's argument
+  count rule.
+- Updated examples to prefer explicit nested class selectors and documented
+  application-lifetime client reuse, HTTP connection pooling, and shutdown.
+- Returned group memberships as contract-validated `PrincipalMember` values
+  and added cursor-aware membership page and collection helpers.
+- Parsed both standard `Retry-After` forms into safe, non-negative rate-limit
+  delays and ignored malformed or non-finite values.
+- Cached lazily created resource-service accessors per client while keeping
+  class-scoped object services on demand.
+
+### Security
+
+- Hardened origin-locked requests against nested URL traversal, ambiguous path
+  characters, and caller-supplied `Host` headers.
+- Made bearer-header replacement case-insensitive and redact request secrets
+  from transport, API, and decoding exception details.
+- Redacted values under sensitive query parameter names from API and transport
+  error diagnostics.
+- Redacted login tokens from model representations.
+
+[Unreleased]: https://github.com/hubuum/hubuum-client-python/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/hubuum/hubuum-client-python/releases/tag/v0.0.1

hubuum_client-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Thank you for helping improve the Hubuum Python client.
+
+## Development setup
+
+Install [uv](https://docs.astral.sh/uv/), clone the repository, and create the
+development environment:
+
+```bash
+uv sync --extra dev
+```
+
+Before opening a pull request, run the same non-container checks as CI:
+
+```bash
+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
+uv build
+```
+
+Changes that affect server behavior should also pass the pinned live-server
+suite:
+
+```bash
+./scripts/run-e2e-tests.sh
+```
+
+## Pull requests
+
+- Keep each pull request focused and explain its user-visible effect.
+- Add tests for behavior changes, including sync and async paths when they can
+  diverge.
+- Update documentation and the `[Unreleased]` changelog section when public
+  behavior, compatibility, or requirements change.
+- Do not include credentials, bearer tokens, server data, or generated build
+  artifacts.
+
+By contributing, you agree that your contribution is licensed under the
+repository's MIT License.

hubuum_client-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hubuum contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.