Initial release

What's Changed

🎉 First public release of python-gazelle — a typed, async-first Python client for Gazelle (https://github.com/WhatCD/Gazelle)-based music trackers, with first-class support for Orpheus and Redacted (RED).

Highlights

Async-first client with sync wrappers

Built on httpx (https://www.python-httpx.org/) and pydantic v2 (https://docs.pydantic.dev/). Use OrpheusClient / RedactedClient as async context managers, or the *Sync variants (OrpheusClientSync, RedactedClientSync) for
blocking code — same interface either way.

Full core API surface

Resource namespaces on every client: .torrents, .artists, .requests, .collages, .user, .inbox, .notifications, .bookmarks, .subscriptions, and .site — all returning typed pydantic models.

Robust transport layer

API-key or cookie/login authentication, built-in token-bucket rate limiting, and automatic retry/backoff on 429/5xx. Per-tracker quirks (auth header format, base URL, required User-Agent) are handled transparently so the same
code works against both Orpheus and RED.

Automation helpers

• Upload/snatch monitoring — TorrentMonitor emits TorrentChangeEvents for tracker activity.
• Cross-seeding — cross_seed, find_candidates, verify_match (plus cross_seed_sync).
• Cross-uploading between trackers — prepare_upload, duplicate_check, map_metadata, submit_upload (plus sync variants).

Typed errors

GazelleError hierarchy: GazelleAuthError, GazelleRateLimitError, GazelleNotFoundError, GazelleAPIError.

Documentation

Full guides + auto-generated API reference at https://technophile-musicfan.github.io/python-gazelle/.

Requirements

Python 3.11+. Install with uv add python-gazelle or pip install python-gazelle.

Known limitations

• Cross-upload's tracker upload-form field mapping is best-effort, pending verification against the live API.

Full Changelog: https://github.com/technophile-musicfan/python-gazelle/commits/v1.0.0