wagnerrp/pytmdb3

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.