🎬 tmdbfusion 🎬

The Blockbuster Python Wrapper for The Movie Database API

🚧 NOW SHOWING IN A TERMINAL NEAR YOU 🚧
🎟️ Get Tickets • 🍿 Showtimes • 🎬 Cast & Crew • 📽️ Director's Cut

📜 THE PLOT Project Overview

🎞️ Logline

tmdbfusion isn't just another API wrapper options it's a cinematic experience for your codebase. Built for the modern Python auteur, it fuses high-performance async capabilities with strict type safety, delivering data faster than a summer blockbuster opening weekend.

🎭 The Premise

The Movie Database (TMDB) is the world's premier source for movie and TV metadata. But interacting with raw HTTP endpoints is like watching a movie without sound you get the picture, but you miss the soul.

tmdbfusion changes the script. It encapsulates the complexity of API pagination, rate limiting, and session management into a sleek, elegant interface. Whether you're building a simple CLI tool or a massive streaming platform, this library provides the special effects you need to dazzle your users.

🎬 Directed By Design

Every frame of this library was crafted with intent:

Dual Audio Tracks: Full support for both Synchronous and Asynchronous (asyncio) runtimes.
High Frame Rate: Powered by httpx and msgspec for lightning-fast serialization.
IMAX Certified: Fully type-hinted data models (no more cryptic dictionaries).
Director's Control: Precise handling of rate limits and retries.

"If requests is the silent era, tmdbfusion is Dolby Atmos." A Developer, probably.

🎟️ BOX OFFICE Installation

📋 The Rider (Requirements)

Before you step onto the red carpet, ensure your trailer is equipped with the following:

Component	Rating	Notes
Python	3.13+	Only the latest tech for this production.
httpx	0.24+	The engine behind the scenes.
msgspec	0.18+	For high-speed parsing stunts.

🎫 Purchase Tickets (Install via pip)

Grab your front-row seat using the standard package manager.

# Standard Admission
pip install tmdbfusion

# VIP Access (Dev Dependencies)
pip install "tmdbfusion[dev]"

🔐 Security Clearance (API Key)

You cannot enter the theater without a ticket. Obtain your API Key from TMDB Settings.

Method A: Environment Variable (Recommended) Export your key to keep it off-camera.

export TMDB_API_KEY="your_api_key_here"

Method B: Direct Pass (Not Recommended for Production) Pass it during client initialization (see Showtimes below).

🏗️ Studio Setup (Development)

If you want to contribute to the sequel, set up the studio lot:

# Clone the reel
git clone https://github.com/xsyncio/tmdbfusion.git
cd tmdbfusion

# Install hatch (The Producer)
pip install hatch


# Run the test screening
hatch run test

🎫 BACKSTAGE PASS Development Tools

The crew uses a specialized toolset to ensure the production quality remains high.

Role	Tool	Command	Description
Stunt Coordinator	Nox	`nox`	Runs the full test suite across multiple python versions.
Script Supervisor	Ruff	`ruff check .`	Enforces `flake8`, `isort`, and other linting rules.
Cinematographer	Ruff Format	`ruff format .`	Auto-formats code to the project style.
Safety Inspector	Mypy	`mypy .`	Strict static type checking to prevent runtime crashes.
Script Doctor	Numpydoc	`nox -s lint`	Validates strict adherence to NumPy docstring standards.
Set Designer	Deptry	`deptry .`	Checks for unused or missing dependencies.
Security Guard	Pip-Audit	`pip-audit`	Scans dependencies for known vulnerabilities.
Distributor	Bump My Version	`bump-my-version show`	Manages versioning and release tagging.
Editor	Towncrier	`towncrier`	Compiles the changelog from fragment files.
Quality Control	Pre-commit	`pre-commit run --all-files`	Runs all checks before you can commit.

Pro Tip: Install the git hooks to auto-run safety checks:
pre-commit install

🍿 SHOWTIMES Quick Start

Grab your popcorn. Here are three feature presentations to get you started.

🎥 Feature Presentation 1: The Classic (Synchronous)

For when you want to enjoy the film one frame at a time.

This example demonstrates the standard synchronous workflow: initializing the client, fetching a movie by ID, and accessing its data model attributes. Note the use of dot-notation for attributes (movie.title) thanks to our type-safe models.

from tmdbfusion import TMDBClient
from tmdbfusion.exceptions import TMDBError

def main():
    # 🎬 ACTION! Initialize the client
    # Pro Tip: Pass api_key=None to read from TMDB_API_KEY env var
    with TMDBClient("your_api_key_here") as client:
        try:
            # Fetch "Fight Club" (ID: 550)
            # The director calls for a close-up on the details
            movie = client.movies.details(550)

            print(f"Title: {movie.title}")
            print(f"Tagline: {movie.tagline}")
            print(f"Budget: ${movie.budget:,.2f}")

        except TMDBError as e:
            # 🎬 CUT! Something went wrong on set.
            print(f"Scene failed: {e}")

if __name__ == "__main__":
    main()

🏎️ Feature Presentation 2: Fast & Furious (Asynchronous)

For when you need speed. Lots of speed.

This example showcases the power of asyncio. We use the AsyncTMDBClient to fetch the first pages of "Popular", "Top Rated", and "Now Playing" movies simultaneously. This is the IMAX way to use the library.

import asyncio
from tmdbfusion import AsyncTMDBClient

async def main():
    async with AsyncTMDBClient("your_api_key_here") as client:
        # Schedule concurrent filming units
        # We fetch three different lists at the exact same time
        tasks = [
            client.movies.popular(),
            client.movies.top_rated(),
            client.movies.now_playing()
        ]
        
        # 🎬 ACTION! Execute all tasks
        results = await asyncio.gather(*tasks)
        popular, top_rated, now_playing = results

        print(f"Popular: {popular.results[0].title}")
        print(f"Top Rated: {top_rated.results[0].title}")
        print(f"Now Playing: {now_playing.results[0].title}")

if __name__ == "__main__":
    asyncio.run(main())

🔄 Feature Presentation 3: The Extended Cut (Auto-Pagination)

Binge-watch the entire series without lifting a finger.

Manually handling page numbers is so 1999. Use the built-in paginate helper to stream results lazily. This iterator handles the page requests for you behind the scenes.

from tmdbfusion import TMDBClient

def main():
    with TMDBClient("your_api_key") as client:
        # Create an iterator for popular movies
        # We start rolling and don't stop strictly at page 1
        iterator = client.paginate(client.movies.popular)

        print("--- Top 20 Movies ---")
        # take(20) ensures we only consume what we need
        for movie in iterator.take(20):
            print(f"⭐ {movie.vote_average} | {movie.title}")

if __name__ == "__main__":
    main()

🎬 CAST & CREW API Reference

👤 The Director: `TMDBClient` / `AsyncTMDBClient`

Import: from tmdbfusion import TMDBClient, AsyncTMDBClient

The Client is the auteur of your application. It manages the connection, handles authentication, and directs the scene.

📝 Constructor

def __init__(
    self,
    api_key: str,
    *,
    access_token: str | None = None,
    language: str = "en-US",
    timeout: float = 30.0,
    retries: int = 3,
    backoff_factor: float = 0.5,
    max_connections: int = 100,
    max_keepalive_connections: int = 20,
    cache_ttl: float | None = None,
    log_hook: Callable[[str, str, int], None] | None = None,
)

📋 Production Notes (Parameters)

Parameter	Type	Default	Description
`api_key`	`str`	Required	Your TMDB API Key (v3).
`access_token`	`str`	`None`	Your API Read Access Token (v4). Required for some v4 endpoints.
`language`	`str`	`"en-US"`	Default language for all requests (ISO 639-1).
`timeout`	`float`	`30.0`	Connection timeout in seconds. Don't be late to the set.
`retries`	`int`	`3`	Application-level retries for 5xx errors and 429s.
`backoff_factor`	`float`	`0.5`	Exponential backoff multiplier.
`cache_ttl`	`float`	`None`	Time-to-live for local caching (seconds). If set, GET requests are cached.

📡 Core Methods

`get()`

Signature: get(id_or_external: int | str, *, append: list[str] | None = None) -> object
Description: The "Magic Lens". Attempts to auto-detect the media type based on the ID format.

If int: Assumes Movie.
If str (e.g., tt12345): Performs a find for IMDb ID.
If str (e.g., tv:123): Explicitly fetches TV show.

`paginate()`

Signature: paginate(method, *, map_response=None, **kwargs) -> PaginatedIterator
Description: Creates a lazy iterator for any API method that accepts a page parameter. Returns: PaginatedIterator (Sync) or AsyncPaginatedIterator (Async) with .take(n) and .skip(n) methods.

`batch()`

Signature: batch(concurrency: int = 10) -> BatchContext
Description: Creates a context manager to queue operations and execute them with controlled concurrency. Usage:

async with client.batch(concurrency=5) as batch:
    for mid in [550, 551, 552]:
        batch.add(client.movies.details(mid))
# Results available after exit
results = batch.results

`sync_config()`

Signature: sync_config() -> None
Description: Fetches the latest API configuration from TMDB and configures the images utility with base URLs.

`close()`

Signature: close() -> None
Description: Cuts the wrap. Closes the underlying HTTP transport.

🌟 The Stars (Core Namespaces)

🎬 `client.movies`

Class: MoviesAPI / AsyncMoviesAPI
Purpose: The headliner. Interfaces with the standard Movie endpoints.

Method	Description
`details`	Get the primary details of a movie.
`popular`	Get a list of the current popular movies.
`top_rated`	Get the top rated movies on TMDB.
`now_playing`	Get a list of movies in theatres.
`upcoming`	Get a list of movies coming soon.
`credits`	Get the cast and crew for a movie.
`recommendations`	Get a list of recommended movies for a movie.
`similar`	Get a list of similar movies.
`images`	Get the images that belong to a movie.
`videos`	Get the videos that have been added to a movie.
`watch_providers`	Get the list of streaming providers.

📜 Method Details: Movies

`details()`

Signature: details(movie_id: int, *, append_to_response: str | None = None) -> MovieDetails
Sync/Async: Both.
Parameters:
- movie_id (int): The ID of the movie.
- append_to_response (str): Comma separated list of extra requests (e.g., "credits,images").
Returns: MovieDetails model.

Usage:

movie = client.movies.details(550, append_to_response="credits")

`popular()`

Signature: popular(*, page: int = 1) -> MoviePaginatedResponse
Sync/Async: Both.
Parameters:
- page (int): Page number (default: 1).
Returns: MoviePaginatedResponse containing list of Movie.
Usage:
```
popular = client.movies.popular(page=2)
```

`top_rated()`

Signature: top_rated(*, page: int = 1) -> MoviePaginatedResponse
Sync/Async: Both.
Parameters: page (int).
Returns: MoviePaginatedResponse.

`credits()`

Signature: credits(movie_id: int) -> Credits
Sync/Async: Both.
Parameters: movie_id (int).
Returns: Credits model (contains cast and crew lists).

Usage:

credits = client.movies.credits(550)
print(credits.cast[0].name)

`images()`

Signature: images(movie_id: int, *, include_image_language: str | None = None) -> ImagesResponse
Sync/Async: Both.
Parameters:
- movie_id (int).
- include_image_language (str): Filter by language (e.g., "en,null").
Returns: ImagesResponse (backdrops, posters, logos).

(All other methods follow similar standard signatures)

📺 `client.tv`

Class: TVAPI / AsyncTVAPI
Purpose: The binge-worthy content. Interfaces with TV Show endpoints.

Method	Description
`details`	Get the primary TV show details.
`popular`	Get a list of the current popular TV shows.
`top_rated`	Get the top rated TV shows.
`on_the_air`	Get a list of shows that are currently on the air.
`airing_today`	Get a list of shows that are airing today.
`credits`	Get the cast and crew.
`external_ids`	Get the external Ids for a TV show.

📜 Method Details: TV

`details()`

Signature: details(tv_id: int, *, append_to_response: str | None = None) -> TVDetails
Sync/Async: Both.
Parameters:
- tv_id (int): The ID of the TV show.
- append_to_response (str).
Returns: TVDetails model.

`on_the_air()`

Signature: on_the_air(*, page: int = 1) -> TVPaginatedResponse
Sync/Async: Both.
Parameters: page (int).
Returns: TVPaginatedResponse.

`season()`

See client.tv_seasons for season-specific endpoints.

🧑 `client.people`

Class: PeopleAPI / AsyncPeopleAPI
Purpose: The talent. Interfaces with People endpoints.

Method	Description
`details`	Get the primary person details.
`movie_credits`	Get the movie credits for a person.
`tv_credits`	Get the TV credits for a person.
`combined_credits`	Get the combined movie and TV credits.
`images`	Get the images for a person.
`popular`	Get the list of popular people.

📜 Method Details: People

`details()`

Signature: details(person_id: int, *, append_to_response: str | None = None) -> PersonDetails
Sync/Async: Both.
Parameters: person_id (int).
Returns: PersonDetails model.
Usage:
```
brad = client.people.details(287)
```

`combined_credits()`

Signature: combined_credits(person_id: int) -> CombinedCredits
Sync/Async: Both.
Parameters: person_id (int).
Returns: CombinedCredits (cast/crew for both media types).

🎭 The Supporting Cast (Discovery & Metadata)

🔍 `client.search`

Class: SearchAPI / AsyncSearchAPI
Purpose: Find what you're looking for.

Method	Description
`movie`	Search for movies.
`tv`	Search for TV shows.
`person`	Search for people.
`multi`	Search for movies, TV shows, and people in a single request.
`collection`	Search for collections.
`company`	Search for companies.
`keyword`	Search for keywords.

📜 Method Details: Search

`movie()`

Signature: movie(query: str, *, page: int = 1, year: int | None = None, ...) -> MoviePaginatedResponse
Parameters: query (str), page, year, primary_release_year, include_adult.

Usage:

results = client.search.movie("The Matrix", year=1999)

`multi()`

Signature: multi(query: str, *, page: int = 1) -> MultiPaginatedResponse
Returns: Mixed list of Movie, TV, and Person objects. Check media_type attribute.

🧭 `client.discover`

Class: DiscoverAPI / AsyncDiscoverAPI
Purpose: The engine of discovery. Filter content by detailed criteria.

Method	Description
`movie`	Discover movies by specified criteria.
`tv`	Discover TV shows by specified criteria.

📜 Method Details: Discover

`movie()`

Signature: movie(**kwargs) -> MoviePaginatedResponse
Parameters: Accepts all standard TMDB discover parameters as kwargs (with_genres, sort_by, primary_release_year, etc.).

Usage:

# Find Action movies from 2023 sorted by revenue
discoveries = client.discover.movie(
    with_genres=28,
    primary_release_year=2023,
    sort_by="revenue.desc"
)

📈 `client.trending`

Class: TrendingAPI / AsyncTrendingAPI
Purpose: What's hot right now.

Method	Description
`movie`	Get trending movies.
`tv`	Get trending TV shows.
`person`	Get trending people.
`all`	Get trending content of all types.

📜 Method Details: Trending

`all()`

Signature: all(time_window: str = "day") -> MultiPaginatedResponse
Parameters: time_window: "day" or "week".
Usage:
```
trending = client.trending.all("week")
```

🕵️ `client.find`

Class: FindAPI / AsyncFindAPI
Purpose: Locate TMDB objects by external IDs (IMDb, TVDB, Facebook, Instagram, Twitter).

`by_id()`

Signature: by_id(external_id: str, *, external_source: str) -> FindResponse
Parameters:
- external_id: The ID from the external source.
- external_source: "imdb_id", "tvdb_id", etc.
Returns: FindResponse containing movie_results, tv_results, etc.

🏷️ `client.genres`

Class: GenresAPI / AsyncGenresAPI
Purpose: Get the list of official genres.

Method	Description
`movie_list`	Get the list of movie genres.
`tv_list`	Get the list of TV genres.

📚 `client.collections`

Class: CollectionsAPI / AsyncCollectionsAPI
Purpose: Get collection details (e.g., "The Avengers Collection").

`details()`

Signature: details(collection_id: int) -> CollectionDetails

🏢 `client.companies`

Class: CompaniesAPI / AsyncCompaniesAPI
Purpose: Get production company details.

`details()`

Signature: details(company_id: int) -> CompanyDetails

🔑 `client.keywords`

Class: KeywordsAPI / AsyncKeywordsAPI
Purpose: Get keyword details.

`details()`

Signature: details(keyword_id: int) -> Keyword

📡 `client.networks`

Class: NetworksAPI / AsyncNetworksAPI
Purpose: Get TV network details.

`details()`

Signature: details(network_id: int) -> Network

📝 `client.reviews`

Class: ReviewsAPI / AsyncReviewsAPI
Purpose: Get full review details.

`details()`

Signature: details(review_id: str) -> Review
Note: review_id is a string (UUID).

📺 `client.watch_providers`

Class: WatchProvidersAPI / AsyncWatchProvidersAPI
Purpose: Get available watch providers and regions.

Method	Description
`movie_providers`	Get available movie providers.
`tv_providers`	Get available TV providers.
`regions`	Get available regions.

📜 Method Details: Watch Providers

`movie_providers()`

Signature: movie_providers(*, watch_region: str = "US") -> WatchProvidersList
Parameters: watch_region: ISO 3166-1 code.

🔐 Behind The Scenes (Account & Auth)

👤 `client.account` (V3)

Class: AccountAPI / AsyncAccountAPI
Purpose: Manage user account data (V3). Requirement: Most methods require a session_id.

Method	Description
`details`	Get your account details.
`favorite_movies`	Get your favorite movies.
`favorite_tv`	Get your favorite TV shows.
`add_favorite`	Mark a movie or TV show as favorite.
`rated_movies`	Get movies you have rated.
`rated_tv`	Get TV shows you have rated.
`rated_episodes`	Get TV episodes you have rated.
`watchlist_movies`	Get movies on your watchlist.
`watchlist_tv`	Get TV shows on your watchlist.
`add_to_watchlist`	Add a movie or TV show to your watchlist.
`lists`	Get lists you have created.

📜 Method Details: Account (V3)

`details()`

Signature: details(*, session_id: str) -> AccountDetails
Parameters: session_id (str).

Usage:

details = client.account.details(session_id="your_session_id")
print(f"Logged in as {details.username}")

`add_favorite()`

Signature: add_favorite(account_id: int, *, session_id: str, media_type: str, media_id: int, favorite: bool) -> StatusResponse
Parameters:
- account_id (int): Your account ID.
- media_type (str): "movie" or "tv".
- favorite (bool): True to add, False to remove.

Usage:

client.account.add_favorite(
    account_id=123,
    session_id="sess_id",
    media_type="movie",
    media_id=550,
    favorite=True
)

🔑 `client.authentication` (V3)

Class: AuthenticationAPI / AsyncAuthenticationAPI
Purpose: Create Sessions and Guest Sessions.

Method	Description
`create_request_token`	Step 1: Create a temporary request token.
`create_session_with_login`	Step 2 (Optional): Validate token with username/password.
`create_session`	Step 3: Create a full session ID.
`create_guest_session`	Create a temporary guest session.
`delete_session`	Logout/Delete a session.

📜 Method Details: Authentication

`create_request_token()`

Returns: RequestToken (contains request_token string).
Note: Redirect user to https://www.themoviedb.org/authenticate/{request_token} for approval if not using direct login.

`create_session()`

Signature: create_session(*, request_token: str) -> Session
Parameters: request_token (approved).
Returns: Session (contains session_id).

🎫 `client.guest_session`

Class: GuestSessionAPI / AsyncGuestSessionAPI
Purpose: Fetch rated items for a guest session.

Method	Description
`rated_movies`	Get rated movies.
`rated_tv`	Get rated TV shows.
`rated_episodes`	Get rated episodes.

🎬 The Sequel: Version 4 API

👤 `client.account_v4`

Class: AccountV4API / AsyncAccountV4API
Purpose: Manage user account data using V4 Access Tokens. Requirement: Use access_token in Client constructor.

Method	Description
`lists`	Get lists.
`favorite_movies`	Get favorite movies.
`favorite_tv`	Get favorite TV shows.
`rated_movies`	Get rated movies.
`rated_tv`	Get rated TV shows.
`movie_recommendations`	Get movie recommendations.
`tv_recommendations`	Get TV recommendations.
`movie_watchlist`	Get movie watchlist.
`tv_watchlist`	Get TV watchlist.

🔐 `client.auth_v4`

Class: AuthV4API / AsyncAuthV4API
Purpose: Manage V4 Request Tokens and Access Tokens.

Method	Description
`create_request_token`	Create a V4 request token.
`create_access_token`	Create a V4 access token.
`delete_access_token`	Delete an access token.

📝 `client.lists_v4`

Class: ListsV4API / AsyncListsV4API
Purpose: Manage V4 Lists.

Method	Description
`details`	Get list details.
`create`	Create a list.
`update`	Update a list.
`delete`	Delete a list.
`add_items`	Add items to list.
`remove_items`	Remove items from list.
`check_item_status`	Check if item is in list.

📅 Lists & Changes (V3)

📝 `client.lists` (V3)

Class: ListsAPI / AsyncListsAPI
Purpose: Get details for public V3 lists.

`details()`

Signature: details(list_id: int | str) -> ListDetails

🔄 `client.changes`

Class: ChangesAPI / AsyncChangesAPI
Purpose: Get listing of ID changes.

Method	Description
`movie`	Get movie change list.
`tv`	Get TV change list.
`person`	Get person change list.

📜 `client.certifications`

Class: CertificationsAPI / AsyncCertificationsAPI
Purpose: Get supported certifications.

Method	Description
`movie_list`	Get movie certifications.
`tv_list`	Get TV certifications.

📽️ DIRECTOR'S CUT Advanced Usage

For the power users who want to go behind the scenes and tweak the lighting.

🔄 Pagination Automagic

The paginate method is a high-level abstraction, but under the hood, it's doing heavy lifting.

# Create an async iterator for popular movies
iterator = client.paginate(client.movies.popular)

# Take 100 items, but skip the first 20
# This automatically handles page boundaries.
# If page 1 has 20 items, it skips page 1 entirely and starts fetching from page 2.
subset = iterator.skip(20).take(100)

async for movie in subset:
    print(movie.title)

⚡ Custom Transport & Caching

You can inject your own logging hooks or adjust the retry logic.

def my_log_hook(method, url, status):
    print(f"🎥 [CUT] {method} {url} -> {status}")

client = TMDBClient(
    "api_key",
    retries=5,                # More persistence
    backoff_factor=1.0,       # Slower backoff
    cache_ttl=3600,           # Cache GET requests for 1 hour
    log_hook=my_log_hook
)

📦 Batching Operations

When you need to fetch data for a grid view (e.g., 20 movies at once), sequential requests are too slow. Use batch().

async with client.batch(concurrency=10) as batch:
    for movie_id in top_20_ids:
        # These are queued, not awaited immediately
        batch.add(client.movies.details(movie_id))

# All results return in the same order they were added
movies = batch.results

🖼️ Image Handling

The images utility helps you construct full URLs for posters and backdrops using the current configuration.

# Ensure config is loaded
client.sync_config()

poster_path = movie.poster_path  # e.g., "/abc.jpg"
url = client.images.get_url(poster_path, "poster", "w500")
print(url)
# Output: https://image.tmdb.org/t/p/w500/abc.jpg

🎬 PRODUCTION NOTES Design Decisions

🏗️ Architecture

We chose msgspec over pydantic for one reason: Speed. When deserializing thousands of movie objects for a data science pipeline or a high-traffic web app, msgspec offers significant performance gains. Every model is a frozen=True Struct, ensuring immutability and thread safety.

🧵 Sync vs Async

Rather than using a single client with asyncio.run() hacks for sync usage, we provide two distinct implementations (TMDBClient and AsyncTMDBClient) that share the same logical structure but use different transport layers (httpx.Client vs httpx.AsyncClient). This ensures that synchronous code is truly blocking and asynchronous code is truly non-blocking, without overhead.

🛡️ Type Safety

We employ Strict mode in our mypy configuration. Optional types are explicit. There are no loose dictionaries returned from the API; everything is validated against a schema. If the API changes and returns an unknown field, we ignore it by default to prevent crashing, but missing required fields will raise validation errors, alerting you to contract breaches immediately.

⚖️ License

Distributed under the MIT License. See LICENSE for more information.

"This is your life and it's ending one minute at a time."

Fight Club (1999)

by Xsyncio
Not endorsed or certified by TMDB.

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
.github/workflows		.github/workflows
docs		docs
tests		tests
tmdbfusion		tmdbfusion
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CODE-STYLE.md		CODE-STYLE.md
LICENSE		LICENSE
README.md		README.md
mkdocs.yml		mkdocs.yml
noxfile.py		noxfile.py
pyproject.toml		pyproject.toml
uv.lock		uv.lock

License

xsyncio/tmdbfusion

Folders and files

Latest commit

History

Repository files navigation

🎬 tmdbfusion 🎬

The Blockbuster Python Wrapper for The Movie Database API

📜 THE PLOT Project Overview

🎞️ Logline

🎭 The Premise

🎬 Directed By Design

🎟️ BOX OFFICE Installation

📋 The Rider (Requirements)

🎫 Purchase Tickets (Install via pip)

🔐 Security Clearance (API Key)

🏗️ Studio Setup (Development)

🎫 BACKSTAGE PASS Development Tools

🍿 SHOWTIMES Quick Start

🎥 Feature Presentation 1: The Classic (Synchronous)

🏎️ Feature Presentation 2: Fast & Furious (Asynchronous)

🔄 Feature Presentation 3: The Extended Cut (Auto-Pagination)

🎬 CAST & CREW API Reference

👤 The Director: TMDBClient / AsyncTMDBClient

📝 Constructor

📡 Core Methods

get()

paginate()

batch()

sync_config()

close()

🌟 The Stars (Core Namespaces)

🎬 client.movies

details()

popular()

top_rated()

credits()

images()

📺 client.tv

details()

on_the_air()

season()

🧑 client.people

details()

combined_credits()

🎭 The Supporting Cast (Discovery & Metadata)

🔍 client.search

movie()

multi()

🧭 client.discover

movie()

📈 client.trending

all()

🕵️ client.find

by_id()

🏷️ client.genres

📚 client.collections

details()

🏢 client.companies

details()

🔑 client.keywords

details()

📡 client.networks

details()

📝 client.reviews

details()

📺 client.watch_providers

movie_providers()

🔐 Behind The Scenes (Account & Auth)

👤 client.account (V3)

details()

add_favorite()

🔑 client.authentication (V3)

create_request_token()

create_session()

🎫 client.guest_session

🎬 The Sequel: Version 4 API

👤 client.account_v4

🔐 client.auth_v4

📝 client.lists_v4

👤 The Director: `TMDBClient` / `AsyncTMDBClient`

`get()`

`paginate()`

`batch()`

`sync_config()`

`close()`

🎬 `client.movies`

`details()`

`popular()`

`top_rated()`

`credits()`

`images()`

📺 `client.tv`

`details()`

`on_the_air()`

`season()`

🧑 `client.people`

`details()`

`combined_credits()`

🔍 `client.search`

`movie()`

`multi()`

🧭 `client.discover`

`movie()`

📈 `client.trending`

`all()`

🕵️ `client.find`

`by_id()`

🏷️ `client.genres`

📚 `client.collections`

`details()`

🏢 `client.companies`

`details()`

🔑 `client.keywords`

`details()`

📡 `client.networks`

`details()`

📝 `client.reviews`

`details()`

📺 `client.watch_providers`

`movie_providers()`

👤 `client.account` (V3)

`details()`

`add_favorite()`

🔑 `client.authentication` (V3)

`create_request_token()`

`create_session()`

🎫 `client.guest_session`

👤 `client.account_v4`

🔐 `client.auth_v4`

📝 `client.lists_v4`

📝 `client.lists` (V3)

`details()`

🔄 `client.changes`

📜 `client.certifications`