proxmox-openapi 0.0.1

pvesh-like CLI for Proxmox API with multi-backend support, performance profiling, and advanced configuration management

proxmox-openapi

Schema-driven FastAPI package for Proxmox API: OpenAPI generation, mock data, and in-memory CRUD operations.

📚 Full Documentation

Features

• Dual Mode: Mock mode (default) for development, Real mode for production Proxmox integration
• 646 Endpoints: Pre-generated Proxmox VE 8.1 API with full OpenAPI schema
• Mock Data: Automatically generate mock data for all endpoints with in-memory CRUD
• Real API Proxy: Validated proxy to real Proxmox VE API with request/response validation
• Code Generation: Automatically crawl Proxmox API Viewer and convert to OpenAPI schema
• Multi-version Support: Select multiple Proxmox versions with latest mapped to official Proxmox API viewer
• Swagger Docs: FastAPI auto-generates OpenAPI documentation at /docs

Installation

pip install proxmox-openapi

Quick Start

Mock Mode (Default)

# Install
pip install proxmox-openapi

# Start server
uvicorn proxmox_openapi.main:app --reload

# View Swagger docs
# Open http://localhost:8000/docs

SDK Direct Usage (No Server Required)

from proxmox_openapi.sdk import ProxmoxSDK

# Async with mock data
async with ProxmoxSDK.mock() as proxmox:
    nodes = await proxmox.nodes.get()

# Or sync (blocking)
with ProxmoxSDK.sync_mock() as proxmox:
    nodes = proxmox.nodes.get()

Real Mode (Connect to Proxmox)

# Configure credentials
export PROXMOX_API_MODE=real
export PROXMOX_URL=https://proxmox.example.com:8006
export PROXMOX_API_TOKEN=PVEAPIToken=user@realm!tokenid=uuid

# Start server
uvicorn proxmox_openapi.main:app --reload

See the Quick Start Guide for more details.

Documentation

• Home - Overview and features
• Installation - Installation options (pip, uv, Docker, source)
• Quick Start - 5-minute getting started guide
• SDK Mock Usage - Using the SDK with mock data (no server required)
• Mock API - Mock mode guide with custom data
• Real API - Real Proxmox integration guide
• API Reference - Endpoint documentation
• Development - Contributing guide
• Architecture - How it works internally
• FAQ - Frequently asked questions

Environment Variables

Mock Mode

• PROXMOX_API_MODE - Set to "mock" (default) or "real"
• PROXMOX_MOCK_SCHEMA_VERSION - Version tag to use (default: "latest")
• PROXMOX_MOCK_DATA_PATH - Path to custom mock data file (default: "/etc/proxmox-openapi/mock-data.json")

Real Mode

• PROXMOX_API_MODE - Set to "real" to enable Proxmox integration
• PROXMOX_URL - Proxmox server URL (e.g., "https://proxmox.example.com:8006")
• PROXMOX_API_TOKEN - API token (recommended, format: "PVEAPIToken=user@realm!tokenid=uuid")
• PROXMOX_USERNAME - Username (fallback, format: "user@realm")
• PROXMOX_PASSWORD - Password (fallback)
• PROXMOX_API_VERIFY_SSL - Verify SSL certificates (default: true)

Server

• HOST - Host to bind to (default: "0.0.0.0")
• PORT - Port to bind to (default: "8000")

Development

# Install dependencies
uv sync --extra test

# Run tests
pytest

# Run linting
ruff check .
ruff format --check .

Docker

# Build the image
docker build -t proxmox-openapi .

# Run the container
docker run -p 8000:8000 proxmox-openapi

License

MIT