pico-httpx 0.1.0

Declarative HTTP clients for the Pico ecosystem: @http_client classes with @get/@post stubs over httpx.

pico-httpx

Declarative HTTP clients for the pico ecosystem: write the interface, get the implementation. Powered by httpx.

Installation

pip install pico-httpx

Quick start

import httpx
from pico_httpx import http_client, get, post

@http_client(base_url="https://api.example.com")   # or resolve from config, see below
class UsersApi:
    @get("/users/{user_id}")
    def get_user(self, user_id: int, verbose: bool | None = None) -> dict: ...

    @post("/users")
    async def create_user(self, json: dict) -> dict: ...

    @get("/users/{user_id}/avatar")
    def avatar(self, user_id: int) -> httpx.Response: ...

The class is a regular @component — inject it anywhere. Rules:

• {placeholders} in the path bind to method parameters.
• A parameter named json is the request body.
• Every other parameter becomes a query param (None values are dropped).
• Return annotation httpx.Response gets the raw response; anything else gets response.json() (or None on an empty body). Non-2xx raises httpx.HTTPStatusError.
• Sync stubs share an httpx.Client, async stubs an httpx.AsyncClient; both close on container shutdown.

Base URL from config instead of code:

http:
  timeout_seconds: 10
  clients:
    users:
      base_url: https://users.internal

@http_client(name="users")
class UsersApi: ...

Compose with the rest of the ecosystem: stack @retryable / @circuit_breaker (pico-resilience) on the same methods, and pico-otel traces the underlying httpx calls.

Documentation

Full documentation: https://dperezcabrera.github.io/pico-httpx/

License

MIT