proxmox-sdk ~ developer guide

[ ~/proxmox-sdk/developer ]tty0


   ___                              ___ ___  _  __
  | _ \_ _ _____ ___ __  _____ __  / __|   \| |/ /
  |  _/ '_/ _ \ \ / /  \/ _ \ \ /  \__ \ |) | ' <
  |_| |_| \___/_\_\_/\_\___/_\_\   |___/___/|_|\_\
   o p e n a p i  ·  f a s t a p i  ·  m o c k + r e a l

emerson@netdevops:~/proxmox-sdk$ ./describe.sh proxmox-sdk

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

proxmox-sdk is a schema-driven Python toolkit. It mirrors the Proxmox VE 8.1 REST surface as 646 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.

›intro

emerson@netdevops:~/proxmox-sdk/developer$ cat README.md | head

›architecture

emerson@netdevops:~/proxmox-sdk/developer$ tree -L 2 src/

├─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/ (646 endpoints, ~5.2 MB OpenAPI schema, Pydantic models). Pre-generated for Proxmox VE 8.1.
├─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).
├─CLI / TUI: proxmox_sdk/proxmox_cli/ ships proxmox, pbx, and proxmox-cli entry points; pbx tui launches the Textual UI. Themes: proxmox_cli/themes/themes.py (DARK, LIGHT, MONOKAI).
├─Rate limiting: SlowAPI on every public route (in-process; works without Redis).

›integrations

emerson@netdevops:~/proxmox-sdk/developer$ ./describe-integrations

› target	› protocol	› library
Proxmox VE / PMG / PBS	HTTPS	aiohttp via backends/https.py
Proxmox host (local)	exec	pvesh wrapper (backends/local.py)
Proxmox host (over SSH)	SSH	Paramiko (ssh_paramiko.py) or openssh-wrapper (openssh.py)
proxbox-api	imported	downstream consumer

› Proxmox VE / PMG / PBS: Auth: API token (auth/token.py) or password/ticket+TOTP (auth/ticket.py). Used in real-proxy mode.
› Proxmox host (local): Direct CLI invocation when running on a Proxmox node.
› Proxmox host (over SSH): Two interchangeable SSH transports.
› proxbox-api: proxbox-api pins proxmox-sdk==0.0.3.post1; netbox-proxbox's E2E stack pulls the dev-nginx image of this repo as its proxmox-e2e-mock container.

›contributing

emerson@netdevops:~/proxmox-sdk/developer$ ./contributing --help

# dev install

install

emerson@netdevops:~$ uv sync

# pre-PR checks

› install hooks

shell

uv run pre-commit install --hook-type pre-commit --hook-type pre-push

› lint
shell
```
uv run ruff check .
```
› format
shell
```
uv run ruff format --check .
```
› type check
shell
```
uv run ty check proxmox_sdk tests
```
› syntax compile
shell
```
uv run python -m compileall proxmox_sdk
```

› tests with coverage

shell

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.

# issue tracker https://github.com/emersonfelipesp/proxmox-sdk/issues

›e2e

emerson@netdevops:~/proxmox-sdk/developer$ ./run-e2e --report

› 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 dev-nginx Docker image act as the E2E boundary. Downstream stacks (netbox-proxbox, proxbox-api) consume that image and run the cross-stack E2E.

The CI pipeline lints, type-checks, runs tests with coverage, and rebuilds three Docker variants (raw / nginx / granian) on every main and testing push.

# commands

› tests with coverage

shell

uv run pytest -n auto --cov=proxmox_sdk --cov-report=term-missing tests

› CLI integration only
shell
```
uv run pytest tests/cli/integration
```

# coverage

├─Spec files: tests/cli/integration/test_backend_integration.py (CLI ↔ SDK bridge against mock server).
├─CI jobs: lint, syntax, test, docker-images (raw / nginx / granian variants pushed on every main / testing commit).
├─Cross-stack E2E: the dev-nginx tag is pulled by netbox-proxbox's e2e-docker.yml and proxbox-api's ci.yml as the proxmox-e2e-mock container — proves the published image is consumable end-to-end.

› ci workflow: .github/workflows/ci.yml

›links

emerson@netdevops:~/proxmox-sdk/developer$ links

repo → https://github.com/emersonfelipesp/proxmox-sdk
docs → https://emersonfelipesp.github.io/proxmox-sdk/
issues → https://github.com/emersonfelipesp/proxmox-sdk/issues

›intro#

›architecture#

›integrations#

›contributing#

›e2e#

›links#

›intro

›architecture

›integrations

›contributing

›e2e

›links