Files

HWANG BYUNGHA 184054c6c1 Initial commit: Vultr API v2 Python wrapper with FastAPI server

- 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>

2026-01-22 01:08:17 +09:00

2.2 KiB

Raw Permalink Blame History

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

# 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

# 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/

2.2 KiB Raw Permalink Blame History