# wagnerrp/pytmdb3 architecture

> Architecture diagram of the GitHub repository wagnerrp/pytmdb3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wagnerrp/pytmdb3
- Repository: https://github.com/wagnerrp/pytmdb3

## Overview

1. **Repository purpose**
   PyTMDB3 is a Python client library for TheMovieDb v3 API. It is not an application; it is a package that exposes a domain model for movies, TV series, people, studios, images, and related metadata.

2. **Public package boundary**
   The `tmdb3` package is the main API surface. `tmdb3/__init__.py` likely re-exports the common entry points described in the README, such as `set_key`, `set_cache`, `set_locale`, search helpers, and entity constructors like `Movie`, `Person`, and `Studio`.

3. **API request flow**
   Calls from user code flow into `tmdb3/tmdb_api.py` and `tmdb3/request.py`. This is the core client boundary that turns high-level operations like search, direct lookup, or property access into TMDB HTTP requests.

4. **Lazy-loaded domain objects**
   The library is object-centric: `Movie`, `Person`, `Collection`, `Series`, `Season`, `Episode`, and related types are exposed as properties and populate data on demand. That means object creation and data retrieval are separated; objects act as handles until a field is accessed.

5. **Search and pagination subsystem**
   Search results are not returned as plain arrays. `tmdb3/pager.py` supports list-like result sets that fetch additional TMDB pages automatically as the caller iterates or indexes beyond the current page. This is the main mechanism for handling the API’s paged search endpoints.

6. **Caching boundary**
   `tmdb3/cache_engine.py`, `tmdb3/cache.py`, `tmdb3/cache_file.py`, and `tmdb3/cache_null.py` form a pluggable cache layer. The request path consults this cache before hitting TMDB, with cache entries keyed by request URL. The default file-backed cache persists data locally; the null cache disables persistence for debugging.

7. **Locale handling**
   `tmdb3/locales.py` centralizes locale state and locale objects. Locale affects how requests are formed and how localized fields are resolved across subsequent queries. The library supports a global default locale plus per-call overrides that propagate through related object fetches.

8. **Authentication and API key management**
   `tmdb3/tmdb_auth.py` handles API key configuration and any future auth-related hooks. The README says authenticated user actions such as rating and watchlists are defined in the model, but full authentication support is not yet implemented.

9. **Error and utility layer**
   `tmdb3/tmdb_exceptions.py` defines the package-specific exception types used across request, cache, and object access paths. `tmdb3/util.py` contains shared helpers used by the rest of the library, likely for parsing, normalization, and common conversions.

10. **Data model breadth**
   The library models multiple TMDB entities and relationships: images (`Backdrop`, `Poster`, `Profile`, `Logo`), media relations (`Cast`, `Crew`, `Genre`, `Release`, `Translation`), and TV structures (`Series`, `Season`, `Episode`). These are not separate services; they are a unified object graph backed by the API.

11. **Image and trailer handling**
   Images and trailers are represented as first-class objects with URL generation and size selection logic. This is an important architectural boundary because the library does not just fetch metadata; it also constructs download URLs for remote assets served by TMDB and related hosts.

12. **Support scripts and packaging**
   `scripts/populate_locale.py` and `scripts/pytmdb3.py` are auxiliary tools rather than runtime components. `setup.py` and `MANIFEST.in` indicate this is distributed as a Python package, with the scripts and package modules bundled for installation and reuse.

Main entry points: [`tmdb3/tmdb_api.py`](https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/tmdb_api.py) (API client), [`tmdb3/request.py`](https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/request.py) (Request), [`tmdb3/__init__.py`](https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/__init__.py) (tmdb3), [`tmdb3/cache_engine.py`](https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/cache_engine.py) (Cache engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_api["Public API"]
  node_pkg_init["tmdb3<br/>package facade<br/>[__init__.py]"]
end

subgraph group_core_runtime["Core Runtime"]
  node_tmdb_api["API client<br/>client core<br/>[tmdb_api.py]"]
  node_request["Request<br/>http transport<br/>[request.py]"]
  node_pager["Pager<br/>paged results<br/>[pager.py]"]
  node_locales["Locales<br/>locale state<br/>[locales.py]"]
  node_auth["Auth<br/>api key<br/>[tmdb_auth.py]"]
  node_util["Util<br/>shared helpers<br/>[util.py]"]
  node_exceptions["Exceptions<br/>error types<br/>[tmdb_exceptions.py]"]
end

subgraph group_cache_layer["Cache Layer"]
  node_cache_engine["Cache engine<br/>cache orchestration<br/>[cache_engine.py]"]
  node_cache_iface["Cache API<br/>cache contract<br/>[cache.py]"]
  node_cache_file[("File cache<br/>persistent cache<br/>[cache_file.py]")]
  node_cache_null[("Null cache<br/>no-op cache<br/>[cache_null.py]")]
end

subgraph group_domain_model["Domain Model"]
  node_movie(("Movie<br/>media entity"))
  node_person(("Person<br/>credit entity"))
  node_series(("Series<br/>tv entity"))
  node_season(("Season<br/>tv child"))
  node_episode(("Episode<br/>tv child"))
  node_images["Images<br/>asset model"]
  node_relations["Relations<br/>metadata model"]
  node_collection(("Collection<br/>media entity"))
end

subgraph group_support["Support"]
  node_populate_locale["Populate locale<br/>utility script<br/>[populate_locale.py]"]
  node_cli_script["CLI script<br/>utility script<br/>[pytmdb3.py]"]
  node_setup["setup.py<br/>packaging<br/>[setup.py]"]
end

node_pkg_init -->|"re-exports"| node_tmdb_api
node_pkg_init -->|"configures"| node_locales
node_pkg_init -->|"configures"| node_auth
node_tmdb_api -->|"uses"| node_request
node_tmdb_api -->|"returns"| node_pager
node_tmdb_api -->|"creates"| node_movie
node_tmdb_api -->|"creates"| node_person
node_tmdb_api -->|"creates"| node_series
node_tmdb_api -->|"creates"| node_collection
node_request -->|"consults"| node_cache_engine
node_cache_engine -->|"abstracts"| node_cache_iface
node_cache_engine -->|"selects"| node_cache_file
node_cache_engine -->|"selects"| node_cache_null
node_request -->|"applies"| node_locales
node_request -->|"includes"| node_auth
node_request -->|"raises"| node_exceptions
node_request -->|"uses"| node_util
node_pager -->|"fetches"| node_request
node_movie -->|"exposes"| node_images
node_movie -->|"contains"| node_relations
node_series -->|"contains"| node_season
node_season -->|"contains"| node_episode
node_cli_script -->|"invokes"| node_pkg_init
node_populate_locale -->|"populates"| node_locales
node_setup -->|"packages"| node_pkg_init

click node_pkg_init "https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/__init__.py"
click node_tmdb_api "https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/tmdb_api.py"
click node_request "https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/request.py"
click node_pager "https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/pager.py"
click node_locales "https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/locales.py"
click node_auth "https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/tmdb_auth.py"
click node_cache_engine "https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/cache_engine.py"
click node_cache_iface "https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/cache.py"
click node_cache_file "https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/cache_file.py"
click node_cache_null "https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/cache_null.py"
click node_util "https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/util.py"
click node_exceptions "https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/tmdb_exceptions.py"
click node_populate_locale "https://github.com/wagnerrp/pytmdb3/blob/master/scripts/populate_locale.py"
click node_cli_script "https://github.com/wagnerrp/pytmdb3/blob/master/scripts/pytmdb3.py"
click node_setup "https://github.com/wagnerrp/pytmdb3/blob/master/setup.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pkg_init toneBlue
class node_tmdb_api,node_request,node_pager,node_locales,node_auth,node_util,node_exceptions toneAmber
class node_cache_engine,node_cache_iface,node_cache_file,node_cache_null toneMint
class node_movie,node_person,node_series,node_season,node_episode,node_images,node_relations,node_collection toneRose
class node_populate_locale,node_cli_script,node_setup toneIndigo
```

## Components

### Public API

Top-level package entry points exposed to user code.

- [tmdb3](https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/__init__.py): package facade · Main package surface re-exporting common entry points. · `tmdb3/__init__.py`

### Core Runtime

Request execution, paging, and locale/auth context.

- [API client](https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/tmdb_api.py): client core · High-level TMDB API operations and object construction. · `tmdb3/tmdb_api.py`
- [Request](https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/request.py): http transport · Builds and executes TMDB HTTP requests. · `tmdb3/request.py`
- [Pager](https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/pager.py): paged results · List-like result set that fetches additional pages on demand. · `tmdb3/pager.py`
- [Locales](https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/locales.py): locale state · Global and per-call locale configuration. · `tmdb3/locales.py`
- [Auth](https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/tmdb_auth.py): api key · API key and future auth-related hooks. · `tmdb3/tmdb_auth.py`
- [Util](https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/util.py): shared helpers · Common parsing and conversion helpers. · `tmdb3/util.py`
- [Exceptions](https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/tmdb_exceptions.py): error types · Package-specific exception hierarchy. · `tmdb3/tmdb_exceptions.py`

### Cache Layer

Pluggable request caching implementations.

- [Cache engine](https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/cache_engine.py): cache orchestration · Selects and consults the active cache backend. · `tmdb3/cache_engine.py`
- [Cache API](https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/cache.py): cache contract · Shared cache interface used by request handling. · `tmdb3/cache.py`
- [File cache](https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/cache_file.py): persistent cache · Default file-backed cache implementation. · `tmdb3/cache_file.py`
- [Null cache](https://github.com/wagnerrp/pytmdb3/blob/master/tmdb3/cache_null.py): no-op cache · Disables persistence for debugging or testing. · `tmdb3/cache_null.py`

### Domain Model

Lazy TMDB entities and related media objects.

- **Movie**: media entity · Lazy-loaded movie handle backed by TMDB data.
- **Person**: credit entity · People and credit metadata.
- **Series**: tv entity · TV series root object.
- **Season**: tv child · Season-level TV object.
- **Episode**: tv child · Episode-level TV object.
- **Images**: asset model · Backdrop, poster, profile, and logo image objects.
- **Relations**: metadata model · Cast, crew, genre, release, and translation objects.
- **Collection**: media entity · Grouped movie collection object.

### Support

Packaging and auxiliary scripts.

- [Populate locale](https://github.com/wagnerrp/pytmdb3/blob/master/scripts/populate_locale.py): utility script · Auxiliary locale data population script. · `scripts/populate_locale.py`
- [CLI script](https://github.com/wagnerrp/pytmdb3/blob/master/scripts/pytmdb3.py): utility script · Support script entry point for the package. · `scripts/pytmdb3.py`
- [setup.py](https://github.com/wagnerrp/pytmdb3/blob/master/setup.py): packaging · Package build and installation metadata. · `setup.py`

## Connections

- tmdb3 → API client: re-exports · Top-level package exposes client entry points through the API layer.
- tmdb3 → Locales: configures · Package surface exposes locale selection and defaults.
- tmdb3 → Auth: configures · Package surface exposes API key setup.
- API client → Request: uses · High-level operations are translated into HTTP requests.
- API client → Pager: returns · Search and list endpoints yield paged result objects.
- API client → Movie: creates · API layer constructs media entity handles.
- API client → Person: creates · API layer constructs people entities.
- API client → Series: creates · API layer constructs TV series entities.
- API client → Collection: creates · API layer constructs collection entities.
- Request → Cache engine: consults · Requests check the configured cache before remote calls.
- Cache engine → Cache API: abstracts · Cache orchestration is built around a shared cache contract.
- Cache engine → File cache: selects · Default backend persists responses on disk.
- Cache engine → Null cache: selects · Null backend disables persistence.
- Request → Locales: applies · Locale state influences request formation and localized fields.
- Request → Auth: includes · Request construction includes API key and auth context.
- Request → Exceptions: raises · Transport and API failures surface as package exceptions.
- Request → Util: uses · Shared helpers support request parsing and normalization.
- Pager → Request: fetches · Additional pages are retrieved through the request layer.
- Movie → Images: exposes · Media entities surface image resources and URLs.
- Movie → Relations: contains · Media entities include cast, crew, genres, releases, and translations.
- Series → Season: contains · TV series are composed of seasons.
- Season → Episode: contains · Seasons are composed of episodes.
- CLI script → tmdb3: invokes · Auxiliary script uses the package entry points.
- Populate locale → Locales: populates · Locale utility script works through locale state and data.
- setup.py → tmdb3: packages · Packaging metadata distributes the library modules.