Arrest

Arrest is a powerful type-safe HTTP client designed for Python, leveraging the robust capabilities of httpx and Pydantic. This utility simplifies the structuring and validation of REST API calls by allowing users to define APIs declaratively in a single, organized manner, covering routes, request and response models, retries, and error handling. By using Arrest, developers benefit from enhanced static analysis, autocomplete, and runtime validation for each API call.

Key Features

• Type Safety: Utilize Pydantic models, dataclasses, dictionaries, lists, and XML models for comprehensive request and response validation.
• Declarative Structure: Organize services, resources, and handlers for a clear API surface, making it easier to maintain and scale.
• Diverse Content Types: Support for various content types including application/json, application/x-www-form-urlencoded, multipart/form-data, and application/xml.
• Built-in Retries: Implement exponential backoff using Tenacity or manage transport-level retries directly through httpx.
• Robust Exception Handling: Customized hooks for different exception types and a clean RequestError for handling transport failures.
• OpenAPI Code Generation: Automatically generate Arrest services and Pydantic models from OpenAPI specifications.
• IDE-friendly Helper: The integrated H() helper allows for convenient handler definitions with keyword-argument autocomplete.
• Unified Response Handling: A single response type that clearly distinguishes between success, client errors, and other HTTP status codes.

Quickstart Example

Here’s a simple example to demonstrate how to use Arrest:

from arrest import H, Resource, Service, GET, POST

user = Resource(
    route="/users",
    handlers=[
        H(GET, "/"),
        H(GET, "/{user_id}"),
        H(POST, "/", request=NewUserRequest, response=UserResponse),
    ],
)

svc = Service(
    name="api",
    url="https://api.example.com/v1",
    resources=[user],
)

# GET /users
resp = await svc.users.get("/")
if resp.is_success:
    print(resp.data)

# POST /users with a type-safe request body
resp = await svc.users.post("/", request=NewUserRequest(name="Alice", email="a@b.com"))

Additional Examples

Use cases are expanded to handle XML, form, and file uploads effortlessly:

from pydantic_xml import BaseXmlModel, element
from arrest.params import Form, File
from arrest.types import UploadFile

# XML request/response definition
class XmlPayload(BaseXmlModel, tag="payload"):  
    key: str = element()  
    value: str = element()  

# Form Data Model
class Login(BaseModel):
    username: str = Form(...)
    password: str = Form(...)

# Profile with Multipart File Upload
class Profile(BaseModel):
    name: str = Form(...)
    avatar: UploadFile = File(...)

OpenAPI Code Generation

Easily generate models and services from an OpenAPI specification with the following command:

arrest --url https://petstore3.swagger.io/api/v3/openapi.json -o ./generated

For comprehensive documentation, visit Arrest Documentation.