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