aiotvdb 0.1.0__tar.gz

aiotvdb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Olivier Balalud
+
+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.

aiotvdb-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: aiotvdb
+Version: 0.1.0
+Summary: An asyncio interface to TheTVDB v4 API (async port of tvdb-v4-python).
+Author-email: Olivier Balalud <olivier.balalud@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/olivierbalalud/aiotvdb
+Project-URL: Repository, https://github.com/olivierbalalud/aiotvdb
+Project-URL: Changelog, https://github.com/olivierbalalud/aiotvdb/blob/master/CHANGELOG.md
+Project-URL: Issues, https://github.com/olivierbalalud/aiotvdb/issues
+Keywords: thetvdb,tvdb,asyncio,async,api,client
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Requires-Dist: respx>=0.21; extra == "test"
+Requires-Dist: pytest-httpserver>=1.0; extra == "test"
+Requires-Dist: pytest-cov>=5; extra == "test"
+Requires-Dist: mypy>=1.8; extra == "test"
+Requires-Dist: pyright>=1.1.350; extra == "test"
+Dynamic: license-file
+
+#  aiotvdb
+asyncio version of tvdb-v4-python
+
+[![CI](https://github.com/olivierbalalud/aiotvdb/actions/workflows/ci.yml/badge.svg)](https://github.com/olivierbalalud/aiotvdb/actions/workflows/ci.yml)
+
+`aiotvdb` is an async port of the official [`tvdb-v4-python`](https://github.com/thetvdb/tvdb-v4-python)
+client for [TheTVDB](https://thetvdb.com) v4 API. It mirrors upstream's method
+surface exactly, but every endpoint is an `async def` coroutine backed by
+[`httpx`](https://www.python-httpx.org/) — so you can run many requests
+concurrently instead of one at a time.
+
+## Installation
+
+Requires Python 3.10+.
+
+```bash
+pip install aiotvdb            # once published
+pip install -e ".[test]"      # for local development (installs test deps)
+```
+
+You will need an API key from your [TheTVDB account](https://thetvdb.com/dashboard/account/apikey).
+Subscriber API keys also take a PIN.
+
+## Getting Started
+
+```python
+import asyncio
+from aiotvdb import TVDB
+
+async def main():
+    async with TVDB("YOUR_API_KEY") as tvdb:          # add a PIN: TVDB(key, "PIN")
+        # Login happens lazily on the first request and is reused afterwards.
+        friends = await tvdb.get_series(79168)
+        print(friends["name"])
+
+        # The payoff: fan out many calls concurrently.
+        ids = [79168, 81189, 73244]
+        series = await asyncio.gather(*(tvdb.get_series(i) for i in ids))
+        print([s["name"] for s in series])
+
+        results = await tvdb.search("Friends", type="series")
+        print(len(results))
+
+asyncio.run(main())
+```
+
+Methods return the raw `data` payload (`dict`/`list`) exactly as TheTVDB returns
+it. Errors raise `TVDBError` subclasses (`TVDBAuthError`, `TVDBResponseError`);
+an expired token is refreshed and the request retried automatically.
+
+Prefer to manage the lifecycle yourself, or share an existing client?
+
+```python
+tvdb = TVDB("YOUR_API_KEY")
+try:
+    await tvdb.get_series(79168)
+finally:
+    await tvdb.aclose()
+```
+
+## Changelog
+
+Release history is recorded in
+[`CHANGELOG.md`](https://github.com/olivierbalalud/aiotvdb/blob/master/CHANGELOG.md),
+following [Keep a Changelog](https://keepachangelog.com) and
+[Semantic Versioning](https://semver.org).
+
+## Development
+
+```bash
+pytest                     # full suite (incl. the ~10s concurrency timing test)
+pytest -m "not timing"     # fast suite, skip wall-clock timing test
+ruff check . && ruff format .
+mypy && pyright            # type checks (strict on src/aiotvdb)
+```
+
+Tests run offline against mocked HTTP (`respx`) and a local socket server
+(`pytest-httpserver`); no API key is needed. Coverage is enforced at 90%.
+
+The library is **fully typed** (PEP 561): it ships a `py.typed` marker, so your
+type checker uses its annotations, and both mypy and pyright run strict over the
+package in CI.
+
+### Live integration tests
+
+A separate, opt-in suite exercises the client against the **real TheTVDB API**
+(`tests/test_live*.py`). It is **skipped by default** — it runs only when you pass
+`--run-live` *and* a `TVDB_APIKEY` is available, so the normal suite and CI never
+need a key or network.
+
+1. Create a `.env` file at the project root (it is git-ignored):
+
+   ```dotenv
+   TVDB_APIKEY=your-api-key-here
+   # TVDB_PIN=your-pin       # only for subscriber/user-supported keys
+   ```
+
+   Get a key from your [TheTVDB account](https://thetvdb.com/dashboard/account/apikey).
+   The `.env` is loaded automatically by `tests/conftest.py`. (Alternatively, export
+   `TVDB_APIKEY` in your shell instead of using `.env`.)
+
+2. Run the live tests with `--run-live`. Use `--no-cov` so the live-only subset
+   doesn't trip the 90% coverage gate:
+
+   ```bash
+   pytest --run-live tests/test_live.py tests/test_live_i18n.py tests/test_live_breadth.py --no-cov
+   pytest --run-live -m live --no-cov      # equivalent: select every live test
+   pytest --run-live --no-cov              # whole suite, live tests included
+   ```
+
+   Without `--run-live` (or without a key) these tests report as skipped.
+
+## Attribution
+
+`aiotvdb` is an **independent async reimplementation** that models the public
+method surface of the official [`tvdb-v4-python`](https://github.com/thetvdb/tvdb-v4-python)
+client — the method names and signatures are kept compatible so it's drop-in
+familiar. The endpoint paths themselves are facts of TheTVDB's public v4 API. The
+implementation here is original async code (httpx-based) and is **not** copied from
+upstream.
+
+Note that the upstream `tvdb-v4-python` project **provides no license information**.
+`aiotvdb`'s own code is licensed under the [MIT License](LICENSE); that license
+covers this project's original work only and implies no endorsement by, or
+relationship with, TheTVDB.
+
+## How this code was produced
+
+> **Transparency notice.** This project is generated using AI. The code, tests, and
+> documentation are produced with **[Claude Code](https://claude.com/claude-code)**
+> (Anthropic), assisted by the **Matt Pocock skills** collection
+> (<https://github.com/mattpocock/skills>) — e.g. the `grill-me` skill was used to
+> stress-test the design, and others (such as `tdd` and `to-prd`) may be used during
+> implementation. Design decisions and their reasoning are recorded in
+> [`docs/PRD.md`](https://github.com/olivierbalalud/aiotvdb/blob/master/docs/PRD.md).

aiotvdb-0.1.0/README.md

@@ -0,0 +1,135 @@
+#  aiotvdb
+asyncio version of tvdb-v4-python
+
+[![CI](https://github.com/olivierbalalud/aiotvdb/actions/workflows/ci.yml/badge.svg)](https://github.com/olivierbalalud/aiotvdb/actions/workflows/ci.yml)
+
+`aiotvdb` is an async port of the official [`tvdb-v4-python`](https://github.com/thetvdb/tvdb-v4-python)
+client for [TheTVDB](https://thetvdb.com) v4 API. It mirrors upstream's method
+surface exactly, but every endpoint is an `async def` coroutine backed by
+[`httpx`](https://www.python-httpx.org/) — so you can run many requests
+concurrently instead of one at a time.
+
+## Installation
+
+Requires Python 3.10+.
+
+```bash
+pip install aiotvdb            # once published
+pip install -e ".[test]"      # for local development (installs test deps)
+```
+
+You will need an API key from your [TheTVDB account](https://thetvdb.com/dashboard/account/apikey).
+Subscriber API keys also take a PIN.
+
+## Getting Started
+
+```python
+import asyncio
+from aiotvdb import TVDB
+
+async def main():
+    async with TVDB("YOUR_API_KEY") as tvdb:          # add a PIN: TVDB(key, "PIN")
+        # Login happens lazily on the first request and is reused afterwards.
+        friends = await tvdb.get_series(79168)
+        print(friends["name"])
+
+        # The payoff: fan out many calls concurrently.
+        ids = [79168, 81189, 73244]
+        series = await asyncio.gather(*(tvdb.get_series(i) for i in ids))
+        print([s["name"] for s in series])
+
+        results = await tvdb.search("Friends", type="series")
+        print(len(results))
+
+asyncio.run(main())
+```
+
+Methods return the raw `data` payload (`dict`/`list`) exactly as TheTVDB returns
+it. Errors raise `TVDBError` subclasses (`TVDBAuthError`, `TVDBResponseError`);
+an expired token is refreshed and the request retried automatically.
+
+Prefer to manage the lifecycle yourself, or share an existing client?
+
+```python
+tvdb = TVDB("YOUR_API_KEY")
+try:
+    await tvdb.get_series(79168)
+finally:
+    await tvdb.aclose()
+```
+
+## Changelog
+
+Release history is recorded in
+[`CHANGELOG.md`](https://github.com/olivierbalalud/aiotvdb/blob/master/CHANGELOG.md),
+following [Keep a Changelog](https://keepachangelog.com) and
+[Semantic Versioning](https://semver.org).
+
+## Development
+
+```bash
+pytest                     # full suite (incl. the ~10s concurrency timing test)
+pytest -m "not timing"     # fast suite, skip wall-clock timing test
+ruff check . && ruff format .
+mypy && pyright            # type checks (strict on src/aiotvdb)
+```
+
+Tests run offline against mocked HTTP (`respx`) and a local socket server
+(`pytest-httpserver`); no API key is needed. Coverage is enforced at 90%.
+
+The library is **fully typed** (PEP 561): it ships a `py.typed` marker, so your
+type checker uses its annotations, and both mypy and pyright run strict over the
+package in CI.
+
+### Live integration tests
+
+A separate, opt-in suite exercises the client against the **real TheTVDB API**
+(`tests/test_live*.py`). It is **skipped by default** — it runs only when you pass
+`--run-live` *and* a `TVDB_APIKEY` is available, so the normal suite and CI never
+need a key or network.
+
+1. Create a `.env` file at the project root (it is git-ignored):
+
+   ```dotenv
+   TVDB_APIKEY=your-api-key-here
+   # TVDB_PIN=your-pin       # only for subscriber/user-supported keys
+   ```
+
+   Get a key from your [TheTVDB account](https://thetvdb.com/dashboard/account/apikey).
+   The `.env` is loaded automatically by `tests/conftest.py`. (Alternatively, export
+   `TVDB_APIKEY` in your shell instead of using `.env`.)
+
+2. Run the live tests with `--run-live`. Use `--no-cov` so the live-only subset
+   doesn't trip the 90% coverage gate:
+
+   ```bash
+   pytest --run-live tests/test_live.py tests/test_live_i18n.py tests/test_live_breadth.py --no-cov
+   pytest --run-live -m live --no-cov      # equivalent: select every live test
+   pytest --run-live --no-cov              # whole suite, live tests included
+   ```
+
+   Without `--run-live` (or without a key) these tests report as skipped.
+
+## Attribution
+
+`aiotvdb` is an **independent async reimplementation** that models the public
+method surface of the official [`tvdb-v4-python`](https://github.com/thetvdb/tvdb-v4-python)
+client — the method names and signatures are kept compatible so it's drop-in
+familiar. The endpoint paths themselves are facts of TheTVDB's public v4 API. The
+implementation here is original async code (httpx-based) and is **not** copied from
+upstream.
+
+Note that the upstream `tvdb-v4-python` project **provides no license information**.
+`aiotvdb`'s own code is licensed under the [MIT License](LICENSE); that license
+covers this project's original work only and implies no endorsement by, or
+relationship with, TheTVDB.
+
+## How this code was produced
+
+> **Transparency notice.** This project is generated using AI. The code, tests, and
+> documentation are produced with **[Claude Code](https://claude.com/claude-code)**
+> (Anthropic), assisted by the **Matt Pocock skills** collection
+> (<https://github.com/mattpocock/skills>) — e.g. the `grill-me` skill was used to
+> stress-test the design, and others (such as `tdd` and `to-prd`) may be used during
+> implementation. Design decisions and their reasoning are recorded in
+> [`docs/PRD.md`](https://github.com/olivierbalalud/aiotvdb/blob/master/docs/PRD.md).

aiotvdb-0.1.0/pyproject.toml

@@ -0,0 +1,95 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aiotvdb"
+version = "0.1.0"
+description = "An asyncio interface to TheTVDB v4 API (async port of tvdb-v4-python)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Olivier Balalud", email = "olivier.balalud@gmail.com" }]
+keywords = ["thetvdb", "tvdb", "asyncio", "async", "api", "client"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "pytest-httpserver>=1.0",
+    "pytest-cov>=5",
+    "mypy>=1.8",
+    "pyright>=1.1.350",
+]
+
+[project.urls]
+Homepage = "https://github.com/olivierbalalud/aiotvdb"
+Repository = "https://github.com/olivierbalalud/aiotvdb"
+Changelog = "https://github.com/olivierbalalud/aiotvdb/blob/master/CHANGELOG.md"
+Issues = "https://github.com/olivierbalalud/aiotvdb/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+aiotvdb = ["py.typed"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+# Endpoint methods return parsed JSON (Any) typed as dict/list at the boundary;
+# that is the library's contract, not an accidental Any leak.
+warn_return_any = false
+files = ["src"]
+
+[tool.pyright]
+include = ["src"]
+pythonVersion = "3.10"
+typeCheckingMode = "strict"
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "--cov --cov-report=term-missing --cov-report=xml --cov-report=html"
+markers = [
+    "timing: wall-clock timing tests (concurrency proof); deselect with -m 'not timing'",
+    "live: opt-in tests against the real TheTVDB API; require --run-live and TVDB_APIKEY",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["aiotvdb"]
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 90
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "W"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["aiotvdb"]

aiotvdb-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aiotvdb-0.1.0/src/aiotvdb/__init__.py

@@ -0,0 +1,22 @@
+"""aiotvdb — an asyncio interface to TheTVDB v4 API.
+
+An async port of the official ``tvdb-v4-python`` client.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from aiotvdb.client import TVDB
+from aiotvdb.exceptions import TVDBAuthError, TVDBError, TVDBResponseError
+
+try:
+    __version__ = version("aiotvdb")
+except PackageNotFoundError:  # pragma: no cover - package not installed
+    __version__ = "0.0.0"
+
+__all__ = [
+    "TVDB",
+    "TVDBAuthError",
+    "TVDBError",
+    "TVDBResponseError",
+    "__version__",
+]