184054c6c1
- vultr_api/: Python library wrapping Vultr API v2 - 17 resource modules (instances, dns, firewall, vpc, etc.) - Pagination support, error handling - server/: FastAPI REST server - All API endpoints exposed via HTTP - X-API-Key header authentication - Swagger docs at /docs - Podman quadlet config for systemd deployment Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
69 lines
2.2 KiB
Markdown
69 lines
2.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
This is a Python wrapper library for the Vultr API v2. It provides a typed, object-oriented interface for managing Vultr cloud infrastructure including compute instances, DNS, firewalls, VPCs, and more.
|
|
|
|
## Development Setup
|
|
|
|
```bash
|
|
# Install in development mode
|
|
cd ~/vultr-api
|
|
pip install -e .
|
|
|
|
# Or add to PYTHONPATH if requests is already installed
|
|
export PYTHONPATH=~/vultr-api:$PYTHONPATH
|
|
|
|
# Install dev dependencies for testing
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
# Run all tests
|
|
pytest
|
|
|
|
# Run with coverage
|
|
pytest --cov=vultr_api
|
|
|
|
# Run a single test file
|
|
pytest tests/test_instances.py
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Client Pattern
|
|
- `VultrClient` (client.py) is the main entry point that holds the API key and HTTP session
|
|
- Resources are initialized as attributes on the client (e.g., `client.instances`, `client.dns`)
|
|
- All HTTP requests flow through `VultrClient._request()` which handles auth, errors, and JSON parsing
|
|
|
|
### Resource Pattern
|
|
- Each API domain has a resource class in `vultr_api/resources/`
|
|
- All resources inherit from `BaseResource` which provides access to the parent client
|
|
- Resources call `self.client.get()`, `self.client.post()`, etc. for API operations
|
|
- Pagination is handled by `VultrClient.paginate()` - resources expose this via `list_all()` methods
|
|
|
|
### Key Resources
|
|
| Resource | File | Description |
|
|
|----------|------|-------------|
|
|
| `account` | account.py | Account info, ACL (IP access control) |
|
|
| `instances` | instances.py | Cloud compute VMs, IPv4/IPv6, VPC attachment |
|
|
| `dns` | dns.py | DNS domains and records |
|
|
| `firewall` | firewall.py | Firewall groups and rules |
|
|
| `vpc` | vpc.py | VPC and VPC 2.0 networks |
|
|
|
|
### Error Handling
|
|
- `VultrAPIError` exception contains `message`, `status_code`, and raw `response`
|
|
- Import from `vultr_api.client import VultrAPIError`
|
|
|
|
## API Authentication
|
|
|
|
The library expects a Vultr API key passed to `VultrClient(api_key="...")`. For examples, use the `VULTR_API_KEY` environment variable.
|
|
|
|
## API Reference
|
|
|
|
Official Vultr API v2 documentation: https://www.vultr.com/api/
|