aiotvdb 0.1.0

An asyncio interface to TheTVDB v4 API (async port of tvdb-v4-python).

aiotvdb

asyncio version of tvdb-v4-python

aiotvdb is an async port of the official tvdb-v4-python client for TheTVDB v4 API. It mirrors upstream's method surface exactly, but every endpoint is an async def coroutine backed by httpx — so you can run many requests concurrently instead of one at a time.

Installation

Requires Python 3.10+.

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. Subscriber API keys also take a PIN.

Getting Started

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?

tvdb = TVDB("YOUR_API_KEY")
try:
    await tvdb.get_series(79168)
finally:
    await tvdb.aclose()

Changelog

Release history is recorded in CHANGELOG.md, following Keep a Changelog and Semantic Versioning.

Development

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):

   TVDB_APIKEY=your-api-key-here
   # TVDB_PIN=your-pin       # only for subscriber/user-supported keys
   

   Get a key from your TheTVDB account. 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:

   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 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; 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 (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.