# proxmox-sdk developer guide

Developer guide — the codegen pipeline, dual mock/real backends, and the integration boundary that downstream stacks depend on.

| Field |Value |
| --- | --- |
| Canonical URL | https://emersonfelipesp.com/proxmox-sdk/developer |
| Showcase | https://emersonfelipesp.com/proxmox-sdk |
| GitHub | https://github.com/emersonfelipesp/proxmox-sdk |
| Releases | https://emersonfelipesp.com/proxmox-sdk/releases |
| Release snapshot synced | 2026-06-21T12:43:39.056Z |

## Intro

proxmox-sdk is a schema-driven Python toolkit. It mirrors the Proxmox VE 9.2 REST surface as 675 typed endpoints, runs in either a mock or a real-proxy mode, and exposes the result as both an in-process SDK and an optional FastAPI server.

This page documents the codegen pipeline that produces the schema, the pluggable backend layer that lets every endpoint resolve against mock data or a real cluster, the contribution workflow, and the integration boundary that downstream stacks (proxbox-api, netbox-proxbox) lean on instead of running their own E2E.

## Architecture

- Single Python package proxmox_sdk. Three runtime modes: full FastAPI server (proxmox_sdk/main.py — mock or real proxy), standalone mock-only entrypoint (proxmox_sdk/mock_main.py — used by the netbox-proxbox + proxbox-api E2E stacks), and pure SDK (no server).
- Standalone SDK: proxmox_sdk/sdk/api.py is ProxmoxSDK (async). proxmox_sdk/sdk/sync.py wraps it synchronously. proxmox_sdk/sdk/resource.py adds attribute-based resource navigation.
- Pluggable backends in proxmox_sdk/sdk/backends/: https.py (aiohttp, real Proxmox), mock.py (in-memory), local.py (pvesh CLI), ssh_paramiko.py and openssh.py (two SSH transports).
- Mock layer: proxmox_sdk/mock/ uses SharedMemoryMockStore (shared-lock, file-backed) and proxmox_sdk/mock/routes.py registers CRUD handlers from the OpenAPI schema dynamically at startup. State can be reset with reset_state() between tests.
- Generated artifacts: proxmox_sdk/generated/ (675 endpoints, Pydantic models). Pre-generated for Proxmox VE 9.2 (9.1.11 retained; CI matrix: latest, 9.2, 9.1.11).
- Multi-version isolation: each schema version gets a stable mock namespace (PROXMOX_MOCK_STATE_NAMESPACE defaults to pmx_{version_tag}). A __schema_fingerprint__ guard on sys.modules prevents stale module re-exec when two versions load in the same process.
- Codegen pipeline: proxmox_sdk/proxmox_codegen/crawler.py (Playwright crawls the official Proxmox API Viewer), normalises output, and proxmox_codegen/pipeline.py emits openapi.json + pydantic_models.py. Triggered manually or via the rate-limited /codegen/generate endpoint (CODEGEN_API_KEY required).
- Automated schema sync: .github/workflows/schema-update.yml detects upstream Proxmox API drift weekly (Monday 03:00 UTC) or on workflow_dispatch, regenerates the schema, verifies SHA integrity, and opens a PR automatically.
- CLI / TUI: proxmox_sdk/proxmox_cli/ ships proxmox, pbx, and proxmox-cli entry points; pbx tui launches the Textual UI with in-app per-module view switching (PVE / PBS / PDM). Themes: proxmox_cli/themes/themes.py (DARK, LIGHT, MONOKAI).
- Rate limiting: SlowAPI on every public route (in-process; works without Redis).

## Integrations

| Target |Protocol |Library |Notes |
| --- | --- | --- | --- |
| Proxmox VE / PMG / PBS | HTTPS | aiohttp via backends/https.py | Auth: API token (auth/token.py) or password/ticket+TOTP (auth/ticket.py). Used in real-proxy mode. |
| Proxmox host (local) | exec | pvesh wrapper (backends/local.py) | Direct CLI invocation when running on a Proxmox node. |
| Proxmox host (over SSH) | SSH | Paramiko (ssh_paramiko.py) or openssh-wrapper (openssh.py) | Two interchangeable SSH transports. |
| proxbox-api | imported | downstream consumer | proxbox-api pins proxmox-sdk==0.0.5.post1; netbox-proxbox's E2E stack pulls one of the per-service image tags (latest-pve, latest-pbs, latest-pdm) of this repo as its proxmox-e2e-mock container, one per matrix cell. |

## Contributing

Development install:

```shell
uv sync
```

Pre-PR checks:

- install hooks: `uv run pre-commit install --hook-type pre-commit --hook-type pre-push`
- lint: `uv run ruff check .`
- format: `uv run ruff format --check .`
- type check: `uv run ty check proxmox_sdk tests`
- syntax compile: `uv run python -m compileall proxmox_sdk`
- tests with coverage: `uv run pytest -n auto --cov=proxmox_sdk --cov-report=term-missing tests`

Code style:

- Linter: ruff (select E4/E7/E9/F/I/ANN201/D103/W).
- Formatter: ruff format.
- Type checker: ty.
- Codegen output (proxmox_sdk/generated/) is regenerated, not edited.

Issues: https://github.com/emersonfelipesp/proxmox-sdk/issues

## End-to-end tests

Framework: pytest + pytest-xdist + pytest-cov. Integration boundary covered via tests/cli/integration/test_backend_integration.py exercising the CLI-to-SDK bridge against the mock server.

proxmox-sdk has no dedicated tests/e2e/ directory — the CLI integration suite plus the published service-tagged Docker images (latest-pve, latest-pbs, latest-pdm) act as the E2E boundary. Downstream stacks (netbox-proxbox, proxbox-api) consume those tags and run the cross-stack E2E in parallel.

v0.0.6 advances the schema to Proxmox VE 9.2 and expands the CI matrix to three versions (latest, 9.2, 9.1.11) — every commit runs the full test suite against each schema version independently, with per-version mock state namespacing to prevent inter-run bleed.

The CI pipeline lints, type-checks, runs tests with coverage, and rebuilds the service-tagged Docker variants (raw / nginx / granian × pve / pbs / pdm) on every main and testing push.

Commands:

- tests with coverage: `uv run pytest -n auto --cov=proxmox_sdk --cov-report=term-missing tests`
- CLI integration only: `uv run pytest tests/cli/integration`

Coverage:

- Spec files: tests/cli/integration/test_backend_integration.py (CLI ↔ SDK bridge against mock server).
- CI schema matrix: [latest, 9.2, 9.1.11] — each cell runs the full test suite with its own PROXMOX_MOCK_STATE_NAMESPACE to prevent shared-state collisions.
- CI jobs: lint, syntax, test, docker-images (raw / nginx / granian variants × pve / pbs / pdm service tags pushed on every main / testing commit).
- Cross-stack E2E: the latest-{pve,pbs,pdm} tags are pulled by netbox-proxbox's e2e-docker.yml and proxbox-api's ci.yml as the proxmox-e2e-mock container — one tag per matrix cell, proving the published images are consumable end-to-end.

CI workflow: .github/workflows/ci.yml (https://github.com/emersonfelipesp/proxmox-sdk/blob/main/.github/workflows/ci.yml)

## Links

| Label |URL |
| --- | --- |
| repo | https://github.com/emersonfelipesp/proxmox-sdk |
| docs | https://emersonfelipesp.com/proxmox-sdk/docs/ |
| issues | https://github.com/emersonfelipesp/proxmox-sdk/issues |