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