audd 1.4.0__tar.gz

audd-1.4.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.env
+.DS_Store

audd-1.4.0/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.4.0] - 2026-05-05
+
+### Changed
+
+- **Brand casing fix.** Class names now match the brand `AudD` (capital D) instead of the previous `Au-d-d` PascalCase: `AudD`, `AsyncAudD`, `AudDError`, `AudDAPIError`, `AudDAuthenticationError`, `AudDQuotaError`, `AudDSubscriptionError`, `AudDCustomCatalogAccessError`, `AudDInvalidRequestError`, `AudDInvalidAudioError`, `AudDRateLimitError`, `AudDStreamLimitError`, `AudDNotReleasedError`, `AudDBlockedError`, `AudDNeedsUpdateError`, `AudDServerError`, `AudDConnectionError`, `AudDSerializationError`, `AudDEvent`. The package import path stays `audd` (lowercase), and the env var stays `AUDD_API_TOKEN`.
+- **README polish.** Streams gets a top-level section that includes tokenless longpoll as a subsection ("Receiving events without exposing your token"); the capability table groups longpoll with streams. Concurrency note moved into Configuration as a brief one-liner. Removed internal "design spec" references from public docstrings.
+
+## [1.3.0] - 2026-05-05
+
+Coordinated v1.3.0 stable release across the audd-sdks family. No breaking
+changes; the version bump signals API stability across all nine SDKs.
+
+The full v0.3.0 polish — env-var auto-pickup, streaming/preview helpers
+with metadata fallback, `onEvent` inspection hook, thread-safe token
+rotation, plus per-language work (JPMS module-info, Kotlin `Flow<LongpollEvent>`,
+Swift `Sendable` + DocC, .NET AOT/source-gen + `IServiceCollection`, Rust
+TLS feature flags + `Serialize`, PHP PSR-3 logger, Python `__repr__` +
+`pretty_print()`, Go `slog` example) is now the v1.3.0 baseline.
+
+## [0.3.0] - 2026-05-05
+
+### Added
+
+- **`RecognitionResult.__repr__` and `EnterpriseMatch.__repr__`** — useful one-line representations for logs / REPL: `<RecognitionResult artist='X' title='Y' timecode='00:56' song_link='https://lis.tn/abc'>`. Empty fields are omitted; `timecode` is always present (it's required server-side).
+- **`RecognitionResult.pretty_print()` / `EnterpriseMatch.pretty_print()`** — debug helper that writes the full model state (typed fields plus any forward-compat extras) as indented JSON to stdout (or a caller-supplied stream). Useful when you want to see exactly what came back over the wire.
+
+### Documentation
+
+- README opens with an explicit "thread-safe / safe for concurrent use" statement.
+
+## [0.2.1] - 2026-05-05
+
+### Improved
+
+- **`streaming_url(provider)` now falls back to the metadata block when `song_link` is non-lis.tn.** Previously returned `None` for YouTube `song_link` values; now picks the direct URL from `apple_music.url` / `spotify.external_urls.spotify` / `deezer.link` / `napster.href` when the corresponding metadata was requested via `return=`. Direct URLs are also now *preferred* over the lis.tn redirect when both paths resolve (no redirect = faster client-side load). YouTube as a provider has no metadata-block fallback (only the lis.tn redirect path).
+- `streaming_urls()` correspondingly returns more entries — every provider with either a direct URL or a lis.tn redirect available.
+
+## [0.2.0] - 2026-05-05
+
+DX polish — env-var auto-pickup, streaming/preview helpers, on_event inspection hook, thread-safe token rotation.
+
+### Added
+
+- **`AUDD_API_TOKEN` env-var fallback** (§7.11): `AudD()` / `AsyncAudD()` constructed without an explicit `api_token` now reads it from `os.environ.get("AUDD_API_TOKEN")`. Raises `ValueError` with a dashboard-link hint if both are missing.
+- **`RecognitionResult.streaming_url(provider)`** (§4.3): returns the `lis.tn` redirect URL for `spotify` / `apple_music` / `deezer` / `napster` / `youtube` (e.g. `https://lis.tn/abc?spotify` 302-redirects to the song's Spotify page). Returns `None` for non-lis.tn `song_link` values (e.g., YouTube ones).
+- **`RecognitionResult.streaming_urls()`** (§4.3): convenience dict of all five providers' redirect URLs.
+- **`RecognitionResult.preview_url()`** (§4.3): first available 30-second preview URL from `apple_music.previews[0].url` → `spotify.preview_url` → `deezer.preview`. Documented caveat about provider TOS.
+- Same `streaming_url` / `streaming_urls` / `thumbnail_url` helpers on `EnterpriseMatch`.
+- **`set_api_token(new_token)`** on `AudD` / `AsyncAudD` (§7.10): thread-safe token rotation via a `threading.Lock`. In-flight requests continue with the old token; subsequent requests use the new one. Validates non-empty.
+- **`on_event` inspection hook** on `AudD` / `AsyncAudD` (§7.7a): a callable receiving `AudDEvent` lifecycle events (kind=`request`/`response`/`exception`, method, url, request_id, http_status, elapsed_ms, error_code, extras). Off by default. Never logs the api_token or request body. Hook exceptions are swallowed at debug level so observability never breaks the request path.
+
+### Internal
+
+- 26 new regression tests (`tests/unit/test_v0_2_polish.py`) covering all four feature areas.
+
+## [0.1.1] - 2026-05-04
+
+Independent code review caught several issues. v0.1.1 fixes them before they propagate to the other 8 language SDKs being modeled on this implementation.
+
+### Fixed
+
+- **C1 — `prepare_source` now returns a per-attempt re-opener.** *Note: the reviewer flagged this as a "silent zero-byte upload on retry" bug, but verification (running the regression test against v0.1.0 source) showed that httpx auto-seeks file handles between `post()` calls, so audd-python v0.1.0 was actually correct.* The re-opener pattern is kept as **defense in depth**: it doesn't depend on the HTTP library's seeking behavior, raises cleanly on unseekable streams (rather than silently sending an empty body), and matches the mandatory pattern other SDKs need (their HTTP libraries may not auto-seek).
+- **C2 — `advanced.find_lyrics` was using READ retry policy.** Fixed to use RECOGNITION (the lyrics endpoint is metered; the spec §7.1 cost-aware retry policy explicitly groups it with `recognize`).
+- **C3 — Code 51 (deprecation warning) was raising unconditionally.** Per spec §6.5, when the server returns code 51 with a usable `result`, the SDK now emits a `DeprecationWarning` and returns the result. Only raises if `result` is absent.
+- **S2 — Non-JSON HTTP errors mapped to `AudDSerializationError`.** A 502 with an HTML body now correctly raises `AudDServerError` preserving the HTTP status; `AudDSerializationError` is reserved for 2xx-with-bad-JSON.
+- **S5 — `LongpollConsumer` silently swallowed HTTP errors.** A 401/403/500 returned `{}` and the consumer looped forever, especially painful in browsers. Now non-2xx raises `AudDServerError`; JSON decode failures raise `AudDSerializationError`.
+- **S6 — `LongpollConsumer` had no retry/timeout knobs.** Per spec §4.1 ("same retry, timeout, transport configurability as the authenticated client"), now accepts `max_retries` and `backoff_factor` and applies READ-class retries on connection failures + 5xx.
+- **S9 — Confusing `FileNotFoundError` for typo'd URLs.** A string source that's neither HTTP(S) nor an existing path now raises `TypeError` with a hint about the URL prefix.
+
+### Added
+
+- **Context-manager protocol** on `AudD`, `AsyncAudD`, `LongpollConsumer`, `AsyncLongpollConsumer` — `with AudD(...) as audd:` / `async with AsyncAudD(...) as audd:` now work.
+
+### Tests
+
+- Added 16 regression tests covering each finding (`tests/unit/test_review_fixes.py`, `tests/unit/test_review_fixes_longpoll.py`). Total: 108 unit + contract tests passing.
+
+## [0.1.0] - 2026-05-04
+
+### Added
+- Sync (`AudD`) and async (`AsyncAudD`) clients with parity for every capability.
+- `recognize(source, *, return_, market, timeout)` — auto-detects URL / path / file-like / bytes sources.
+- `recognize_enterprise(source, ...)` with 1-hour read timeout default.
+- `streams.*` namespace: `set_callback_url(url, return_metadata=...)`, `get_callback_url`, `add`, `set_url`, `delete`, `list`, `longpoll(category, *, skip_callback_check=False)` with default-on preflight, plus pure helpers `derive_longpoll_category` and `parse_callback`.
+- `custom_catalog.add(audio_id, source)` — namespaced with NOT-for-recognition warning docstring; 904 errors raise `AudDCustomCatalogAccessError`.
+- `advanced.*` namespace: `find_lyrics(query)`, `raw_request(method, params)` escape hatch.
+- Tokenless `LongpollConsumer` / `AsyncLongpollConsumer` for browser/widget contexts.
+- Forward-compatible Pydantic v2 models with `extra="allow"` on every type.
+- Full error hierarchy mapped to the 25+ AudD error codes.
+- Cost-aware retry policy: read endpoints retry 408/429/5xx; recognition endpoints don't retry post-upload read timeouts (cost protection); mutating endpoints retry only pre-upload connection failures.
+- CI: ruff + mypy strict + pytest matrix on Py 3.9–3.13 (`ci.yml`); contract tests on push/PR + daily cron + `openapi-updated` repository_dispatch (`contract.yml`); tag-triggered PyPI publishing with Sigstore attestation (`release.yml`).

audd-1.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AudD (https://audd.io)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

audd-1.4.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: audd
+Version: 1.4.0
+Summary: Official Python SDK for the AudD music recognition API.
+Project-URL: Homepage, https://audd.io
+Project-URL: Documentation, https://docs.audd.io
+Project-URL: Source, https://github.com/AudDMusic/audd-python
+Project-URL: Issues, https://github.com/AudDMusic/audd-python/issues
+Author-email: AudD <api@audd.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audd,audio,fingerprinting,music-recognition
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: anyio>=4
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.5
+Provides-Extra: dev
+Requires-Dist: jsonschema>=4.21; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Requires-Dist: referencing>=0.35; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# audd
+
+[![CI](https://github.com/AudDMusic/audd-python/actions/workflows/ci.yml/badge.svg)](https://github.com/AudDMusic/audd-python/actions/workflows/ci.yml)
+[![Contract](https://github.com/AudDMusic/audd-python/actions/workflows/contract.yml/badge.svg)](https://github.com/AudDMusic/audd-python/actions/workflows/contract.yml)
+[![PyPI](https://img.shields.io/pypi/v/audd.svg)](https://pypi.org/project/audd/)
+[![Python versions](https://img.shields.io/pypi/pyversions/audd.svg)](https://pypi.org/project/audd/)
+
+Official Python SDK for the [AudD](https://audd.io) music recognition API.
+
+## Quickstart
+
+```bash
+pip install audd
+```
+
+```python
+from audd import AudD
+
+audd = AudD(api_token="test")  # use your token from https://dashboard.audd.io
+result = audd.recognize("https://audd.tech/example.mp3")
+if result:
+    print(f"{result.artist} — {result.title}")
+```
+
+## Capabilities
+
+| What | How |
+|---|---|
+| Recognize a short clip (≤25s) | `audd.recognize(source)` |
+| Recognize a long file (hours, days) | `audd.recognize_enterprise(source, limit=...)` |
+| Manage stream recognition (set callback, longpoll for events) | `audd.streams.*` |
+
+`source` accepts a URL, a file path, a file-like object, or raw bytes — auto-detected.
+
+## Async
+
+Use `AsyncAudD` instead — same surface:
+
+```python
+from audd import AsyncAudD
+
+async def main():
+    audd = AsyncAudD(api_token="test")
+    try:
+        result = await audd.recognize("https://audd.tech/example.mp3")
+        print(result)
+    finally:
+        await audd.aclose()
+```
+
+## Errors
+
+Every server error becomes a typed exception:
+
+```python
+from audd import AudD, AudDAuthenticationError, AudDSubscriptionError
+
+try:
+    AudD(api_token="bad").recognize("https://x.mp3")
+except AudDAuthenticationError as e:
+    print(f"check your token: {e.error_code} {e.message}")
+except AudDSubscriptionError:
+    print("this endpoint isn't enabled on your token")
+```
+
+The full hierarchy is documented in [`src/audd/errors.py`](src/audd/errors.py). Every `AudDAPIError` carries `error_code`, `message`, `http_status`, `request_id`, `requested_params`, `request_method`, `branded_message`, and `raw_response`.
+
+## Forward compatibility
+
+Models accept and round-trip unknown server fields via `model_extra`:
+
+```python
+result = audd.recognize("https://example.mp3", return_=["apple_music"])
+print(result.apple_music.url)               # typed
+print(result.model_extra)                   # any other unknown fields
+```
+
+If AudD adds a new metadata block tomorrow (e.g., `tidal`), you can read it as `result.model_extra["tidal"]` *today* — no SDK release needed. The next SDK release adds the typed `tidal` field, and both paths keep working.
+
+## Streams
+
+Manage real-time stream recognition (set callback, longpoll for events):
+
+```python
+audd.streams.set_callback_url("https://your.server/cb")
+audd.streams.add("https://your.stream.url", radio_id=42)
+for event in audd.streams.list():
+    print(event)
+```
+
+### Receiving events without exposing your token
+
+For browser widgets and other contexts where shipping the api_token would leak it,
+derive a `category` server-side and share that with the consumer:
+
+```python
+from audd import LongpollConsumer
+
+# `category` is derived server-side via AudD(...).streams.derive_longpoll_category(radio_id),
+# then shared with the browser/widget. The consumer carries no api_token.
+consumer = LongpollConsumer(category="abc123def")
+for event in consumer.iterate(timeout=30):
+    print(event)
+```
+
+## Configuration
+
+```python
+import httpx
+from audd import AudD
+
+audd = AudD(
+    api_token="...",
+    max_retries=3,           # retry budget per call
+    backoff_factor=0.5,      # initial backoff seconds (jittered)
+    httpx_client=httpx.Client(proxies="http://corp-proxy:8080"),
+)
+```
+
+Default timeouts: 30s connect / 60s read for standard endpoints, 30s connect / **1 hour** read for the enterprise endpoint. Pass `timeout=` per call to override.
+
+**Concurrency:** `AudD` and `AsyncAudD` are safe for concurrent use — share one instance across threads or asyncio tasks. `set_api_token(...)` rotates the token safely; in-flight requests continue with the old token, subsequent requests use the new one.
+
+## Custom catalog (advanced — not for music recognition)
+
+> ⚠ **The custom-catalog endpoint is NOT how you submit audio for music recognition.**
+> For recognition, use `recognize()` or `recognize_enterprise()`. The custom-catalog
+> endpoint adds songs to your private fingerprint database for *your* account.
+> Requires special access — contact api@audd.io if you need it.
+
+```python
+audd.custom_catalog.add(audio_id=42, source="https://my.song.mp3")
+```
+
+## Advanced
+
+For endpoints not yet wrapped by typed methods on this SDK, use the raw-request escape hatch:
+
+```python
+raw = audd.advanced.raw_request("someNewMethod", {"q": "x"})
+```
+
+## Spec contract
+
+This SDK builds against the [`audd-openapi`](https://github.com/AudDMusic/audd-openapi) spec. The contract tests in `tests/contract/` validate the parser against the canonical fixture set on every push, on a daily cron, and on every spec update.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Support
+
+- Documentation: https://docs.audd.io
+- Tokens: https://dashboard.audd.io
+- Email: api@audd.io

audd-1.4.0/README.md

@@ -0,0 +1,155 @@
+# audd
+
+[![CI](https://github.com/AudDMusic/audd-python/actions/workflows/ci.yml/badge.svg)](https://github.com/AudDMusic/audd-python/actions/workflows/ci.yml)
+[![Contract](https://github.com/AudDMusic/audd-python/actions/workflows/contract.yml/badge.svg)](https://github.com/AudDMusic/audd-python/actions/workflows/contract.yml)
+[![PyPI](https://img.shields.io/pypi/v/audd.svg)](https://pypi.org/project/audd/)
+[![Python versions](https://img.shields.io/pypi/pyversions/audd.svg)](https://pypi.org/project/audd/)
+
+Official Python SDK for the [AudD](https://audd.io) music recognition API.
+
+## Quickstart
+
+```bash
+pip install audd
+```
+
+```python
+from audd import AudD
+
+audd = AudD(api_token="test")  # use your token from https://dashboard.audd.io
+result = audd.recognize("https://audd.tech/example.mp3")
+if result:
+    print(f"{result.artist} — {result.title}")
+```
+
+## Capabilities
+
+| What | How |
+|---|---|
+| Recognize a short clip (≤25s) | `audd.recognize(source)` |
+| Recognize a long file (hours, days) | `audd.recognize_enterprise(source, limit=...)` |
+| Manage stream recognition (set callback, longpoll for events) | `audd.streams.*` |
+
+`source` accepts a URL, a file path, a file-like object, or raw bytes — auto-detected.
+
+## Async
+
+Use `AsyncAudD` instead — same surface:
+
+```python
+from audd import AsyncAudD
+
+async def main():
+    audd = AsyncAudD(api_token="test")
+    try:
+        result = await audd.recognize("https://audd.tech/example.mp3")
+        print(result)
+    finally:
+        await audd.aclose()
+```
+
+## Errors
+
+Every server error becomes a typed exception:
+
+```python
+from audd import AudD, AudDAuthenticationError, AudDSubscriptionError
+
+try:
+    AudD(api_token="bad").recognize("https://x.mp3")
+except AudDAuthenticationError as e:
+    print(f"check your token: {e.error_code} {e.message}")
+except AudDSubscriptionError:
+    print("this endpoint isn't enabled on your token")
+```
+
+The full hierarchy is documented in [`src/audd/errors.py`](src/audd/errors.py). Every `AudDAPIError` carries `error_code`, `message`, `http_status`, `request_id`, `requested_params`, `request_method`, `branded_message`, and `raw_response`.
+
+## Forward compatibility
+
+Models accept and round-trip unknown server fields via `model_extra`:
+
+```python
+result = audd.recognize("https://example.mp3", return_=["apple_music"])
+print(result.apple_music.url)               # typed
+print(result.model_extra)                   # any other unknown fields
+```
+
+If AudD adds a new metadata block tomorrow (e.g., `tidal`), you can read it as `result.model_extra["tidal"]` *today* — no SDK release needed. The next SDK release adds the typed `tidal` field, and both paths keep working.
+
+## Streams
+
+Manage real-time stream recognition (set callback, longpoll for events):
+
+```python
+audd.streams.set_callback_url("https://your.server/cb")
+audd.streams.add("https://your.stream.url", radio_id=42)
+for event in audd.streams.list():
+    print(event)
+```
+
+### Receiving events without exposing your token
+
+For browser widgets and other contexts where shipping the api_token would leak it,
+derive a `category` server-side and share that with the consumer:
+
+```python
+from audd import LongpollConsumer
+
+# `category` is derived server-side via AudD(...).streams.derive_longpoll_category(radio_id),
+# then shared with the browser/widget. The consumer carries no api_token.
+consumer = LongpollConsumer(category="abc123def")
+for event in consumer.iterate(timeout=30):
+    print(event)
+```
+
+## Configuration
+
+```python
+import httpx
+from audd import AudD
+
+audd = AudD(
+    api_token="...",
+    max_retries=3,           # retry budget per call
+    backoff_factor=0.5,      # initial backoff seconds (jittered)
+    httpx_client=httpx.Client(proxies="http://corp-proxy:8080"),
+)
+```
+
+Default timeouts: 30s connect / 60s read for standard endpoints, 30s connect / **1 hour** read for the enterprise endpoint. Pass `timeout=` per call to override.
+
+**Concurrency:** `AudD` and `AsyncAudD` are safe for concurrent use — share one instance across threads or asyncio tasks. `set_api_token(...)` rotates the token safely; in-flight requests continue with the old token, subsequent requests use the new one.
+
+## Custom catalog (advanced — not for music recognition)
+
+> ⚠ **The custom-catalog endpoint is NOT how you submit audio for music recognition.**
+> For recognition, use `recognize()` or `recognize_enterprise()`. The custom-catalog
+> endpoint adds songs to your private fingerprint database for *your* account.
+> Requires special access — contact api@audd.io if you need it.
+
+```python
+audd.custom_catalog.add(audio_id=42, source="https://my.song.mp3")
+```
+
+## Advanced
+
+For endpoints not yet wrapped by typed methods on this SDK, use the raw-request escape hatch:
+
+```python
+raw = audd.advanced.raw_request("someNewMethod", {"q": "x"})
+```
+
+## Spec contract
+
+This SDK builds against the [`audd-openapi`](https://github.com/AudDMusic/audd-openapi) spec. The contract tests in `tests/contract/` validate the parser against the canonical fixture set on every push, on a daily cron, and on every spec update.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Support
+
+- Documentation: https://docs.audd.io
+- Tokens: https://dashboard.audd.io
+- Email: api@audd.io

audd-1.4.0/pyproject.toml

@@ -0,0 +1,91 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "audd"
+dynamic = ["version"]
+description = "Official Python SDK for the AudD music recognition API."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "AudD", email = "api@audd.io" }]
+keywords = ["audd", "music-recognition", "audio", "fingerprinting"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Multimedia :: Sound/Audio :: Analysis",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+  "pydantic>=2.5,<3",
+  "anyio>=4",
+]
+
+[project.urls]
+Homepage = "https://audd.io"
+Documentation = "https://docs.audd.io"
+Source = "https://github.com/AudDMusic/audd-python"
+Issues = "https://github.com/AudDMusic/audd-python/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+  "respx>=0.21",
+  "mypy>=1.10",
+  "ruff>=0.5",
+  "pyyaml>=6",
+  "jsonschema>=4.21",
+  "referencing>=0.35",
+]
+
+[tool.hatch.version]
+path = "src/audd/_version.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/audd", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/audd"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+markers = [
+  "integration: opt-in tests that hit the live AudD API (requires AUDD_API_TOKEN env var)",
+]
+
+[tool.mypy]
+strict = true
+python_version = "3.9"
+files = ["src/audd"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "N", "PL", "RUF"]
+ignore = [
+  "PLR0913",  # too many args — recognize_enterprise legitimately has many kwargs
+  "PLC0415",  # lazy imports inside namespace getters break circular imports
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["PLR2004", "PLR0915", "S101", "E501"]  # magic values, long tests, asserts, line length
+"examples/**/*.py" = ["PLR2004"]  # argv-count comparisons in example scripts
+"src/audd/models.py" = ["N815"]  # Apple Music/Napster ship camelCase JSON keys; field names must match

audd-1.4.0/src/audd/__init__.py

@@ -0,0 +1,46 @@
+"""Official Python SDK for the AudD music recognition API."""
+from audd._version import __version__
+from audd.client import AsyncAudD, AudD
+from audd.errors import (
+    AudDAPIError,
+    AudDAuthenticationError,
+    AudDBlockedError,
+    AudDConnectionError,
+    AudDCustomCatalogAccessError,
+    AudDError,
+    AudDInvalidAudioError,
+    AudDInvalidRequestError,
+    AudDNeedsUpdateError,
+    AudDNotReleasedError,
+    AudDQuotaError,
+    AudDRateLimitError,
+    AudDSerializationError,
+    AudDServerError,
+    AudDStreamLimitError,
+    AudDSubscriptionError,
+)
+from audd.longpoll import AsyncLongpollConsumer, LongpollConsumer
+
+__all__ = [
+    "AsyncAudD",
+    "AsyncLongpollConsumer",
+    "AudD",
+    "AudDAPIError",
+    "AudDAuthenticationError",
+    "AudDBlockedError",
+    "AudDConnectionError",
+    "AudDCustomCatalogAccessError",
+    "AudDError",
+    "AudDInvalidAudioError",
+    "AudDInvalidRequestError",
+    "AudDNeedsUpdateError",
+    "AudDNotReleasedError",
+    "AudDQuotaError",
+    "AudDRateLimitError",
+    "AudDSerializationError",
+    "AudDServerError",
+    "AudDStreamLimitError",
+    "AudDSubscriptionError",
+    "LongpollConsumer",
+    "__version__",
+]