arr-py-client 0.4.0

Typed sync + async Python client for Radarr v3 and Sonarr v3 APIs

arr-py-client

Typed synchronous and asynchronous Python client for Radarr and Sonarr v3 APIs.

Features

• Pydantic v2 models for every request and response
• Sync (RadarrClient, SonarrClient) and async (AsyncRadarrClient, AsyncSonarrClient) clients sharing the same API
• Full v3 endpoint coverage for both apps, generated from upstream OpenAPI specs
• Typed exceptions (ArrNotFoundError, ArrValidationError, etc.) with validation-detail parsing
• Env / .env fallback for credentials via pydantic-settings
• Configurable retry policy (idempotent GET only by default)
• Ships py.typed (PEP 561) — IDEs and type checkers just work
• Python 3.11–3.14

Install

pip install arr-py-client

Quickstart

from arr_py_client import RadarrClient

with RadarrClient(base_url="http://radarr:7878", api_key="YOUR_KEY") as client:
    movies = client.movies.list()
    for m in movies[:5]:
        print(m.id, m.title, m.year)

Or via environment variables — set RADARR_BASE_URL and RADARR_API_KEY and:

from arr_py_client import RadarrClient

with RadarrClient() as client:
    print(len(client.movies.list()))

Async mirrors the sync API:

from arr_py_client import AsyncRadarrClient

async def main() -> None:
    async with AsyncRadarrClient() as client:
        movies = await client.movies.list()
        print(len(movies))

The client also exposes auto-generated wrappers for every OpenAPI tag — for example client.tag.list_(), client.queue.list_(), client.system.list_status(). Method names follow <verb>[_<distinguisher>] (e.g., list_, get_by_id, create, update_by_id, delete_by_id).

Compared to pyarr

	arr-py-client	pyarr
Pydantic v2 models	yes	no (returns dicts)
Async support	yes	no
Full Radarr/Sonarr v3 coverage	yes	yes
Lidarr/Readarr/Prowlarr	not yet	yes
Ships py.typed	yes	no

Documentation

API reference: https://allada-homelab.github.io/arr-py-client/

Development

git clone https://github.com/allada-homelab/arr-py-client
cd arr-py-client
uv sync --all-groups
just test

Integration tests (require Docker):

just test-int

Regenerate clients from upstream specs:

just gen-radarr <radarr-tag>
just gen-sonarr <sonarr-tag>

Contributing

See CONTRIBUTING.md for setup, common recipes, and the release process.

License

MIT. See LICENSE.