"""
Pydantic models for API response validation.
Replaces JSON schema files with type-safe Python models.
Each model corresponds to a former .json schema in tests/schemas/.
.. module:: tests.schemas.models
:synopsis: Pydantic response models for TMDB API validation.
:no-index:
"""
from typing import Optional
from pydantic import BaseModel, Field, StrictBool, StrictFloat, StrictInt, StrictStr, create_model
[docs]
class GenericResponse(BaseModel):
"""
Schema for generic error/status responses.
Used to validate error responses across all endpoints when the API
returns a status message instead of resource data (e.g., 404, 401).
Replaces: ``generic_schema.json``
Example response::
{"status_message": "Resource not found.", "success": false, "status_code": 34}
"""
model_config = {"extra": "forbid"} # error body is exactly these three fields
status_message: StrictStr = Field(min_length=1)
success: StrictBool
status_code: StrictInt = Field(ge=0)
[docs]
class RatingResponse(BaseModel):
"""
Schema for add/delete movie rating responses.
Validates the response structure when a rating is submitted or removed.
Uses ``extra = "forbid"`` to reject any unexpected fields, matching the
strict ``additionalProperties: false`` from the original JSON schema.
Replaces: ``add_delete_rating_schema.json``
Example response::
{"success": true, "status_code": 1, "status_message": "Success."}
"""
model_config = {"extra": "forbid"} # equivalent to additionalProperties: false
success: StrictBool
status_code: StrictInt = Field(ge=0)
status_message: StrictStr = Field(min_length=1)
# Nested model for production companies
[docs]
class ProductionCompany(BaseModel):
"""
Nested model for a production company within movie details.
:param id: Unique identifier for the production company.
:param logo_path: Path to the company logo image, or None if unavailable.
:param name: Name of the production company.
:param origin_country: ISO 3166-1 country code of the company's origin.
"""
id: StrictInt = Field(ge=0)
logo_path: Optional[str] = Field(default=None, pattern=r".*\.(png|jpg)$")
name: StrictStr = Field(min_length=1)
origin_country: Optional[str] = None
# Nested model for genres
[docs]
class Genre(BaseModel):
"""
Nested model for a movie genre.
:param id: Unique identifier for the genre.
:param name: Display name of the genre (e.g., "Action", "Comedy").
"""
id: StrictInt = Field(ge=0)
name: StrictStr = Field(min_length=1)
[docs]
class MovieDetails(BaseModel):
"""
Schema for movie details response from ``GET /3/movie/{movie_id}``.
Validates the core fields returned by the TMDB movie details endpoint.
Uses ``extra = "allow"`` to accept additional fields not explicitly
defined here (e.g., overview, budget, revenue, runtime).
Replaces: ``movie_schema.json``
:param adult: Whether the movie is classified as adult content.
:param id: Unique TMDB movie identifier.
:param origin_country: List of ISO 3166-1 country codes.
:param original_language: ISO 639-1 language code of the original language.
:param original_title: Original title in the movie's native language.
:param title: Localized title of the movie.
:param release_date: Release date in ``YYYY-MM-DD`` format, or None.
:param production_companies: List of companies that produced the movie.
:param genres: List of genres the movie belongs to.
"""
adult: StrictBool
id: StrictInt = Field(ge=0)
origin_country: list[str] # may be empty
original_language: StrictStr = Field(min_length=2, max_length=2) # ISO 639-1
original_title: StrictStr = Field(min_length=1)
title: StrictStr = Field(min_length=1)
release_date: Optional[str] = None
production_companies: list[ProductionCompany] # may be empty
genres: list[Genre] # may be empty
model_config = {"extra": "allow"} # allow fields not defined here (overview, etc.)
# Nested model for movie list items
[docs]
class MovieListItem(BaseModel):
"""
Nested model for a single movie in a paginated movie list.
Represents one item in the ``results`` array shared by TMDB's list-style
endpoints (e.g. ``GET /3/movie/popular``, ``GET /3/search/movie``).
:param adult: Whether the movie is classified as adult content.
:param backdrop_path: Path to the backdrop image, or None.
:param genre_ids: List of genre IDs associated with the movie.
:param id: Unique TMDB movie identifier.
:param original_language: ISO 639-1 language code.
:param original_title: Original title in the movie's native language.
:param overview: Brief plot summary.
:param popularity: TMDB popularity score.
:param poster_path: Path to the poster image, or None.
:param release_date: Release date in ``YYYY-MM-DD`` format.
:param title: Localized title of the movie.
:param video: Whether the movie has an associated video.
:param vote_average: Average user rating (0.0–10.0).
:param vote_count: Total number of user votes.
"""
adult: StrictBool
backdrop_path: Optional[str] = Field(default=None, pattern=r".*\.(png|jpg)$")
genre_ids: list[int] # may be empty
id: StrictInt = Field(ge=0)
original_language: StrictStr = Field(min_length=2, max_length=2) # ISO 639-1
original_title: StrictStr = Field(min_length=1)
overview: str # may be empty
popularity: StrictFloat = Field(ge=0)
poster_path: Optional[str] = Field(default=None, pattern=r".*\.(png|jpg)$")
release_date: str # may be empty
title: StrictStr = Field(min_length=1)
video: StrictBool
vote_average: StrictFloat = Field(ge=0, le=10)
vote_count: StrictInt = Field(ge=0)
model_config = {"extra": "allow"}
[docs]
class SearchMovieListItem(MovieListItem):
"""
Nested model for a single movie in ``GET /3/search/movie`` results.
Search results can include stub catalog entries (e.g. user-submitted
placeholders with no genres, votes or release date). TMDB omits the
corresponding keys entirely for such items rather than sending nulls,
so the fields ``MovieListItem`` requires are made optional here. When a
field *is* present it is still validated with the same strict type and
bounds as the base model; only the presence requirement is relaxed.
:param genre_ids: List of genre IDs, or None when omitted.
:param popularity: TMDB popularity score, or None when omitted.
:param release_date: Release date in ``YYYY-MM-DD`` format, or None when omitted.
:param video: Whether the movie has an associated video, or None when omitted.
:param vote_average: Average user rating (0.0–10.0), or None when omitted.
:param vote_count: Total number of user votes, or None when omitted.
"""
genre_ids: Optional[list[int]] = None # may be empty
popularity: Optional[StrictFloat] = Field(default=None, ge=0)
release_date: Optional[str] = None # may be empty
video: Optional[StrictBool] = None
vote_average: Optional[StrictFloat] = Field(default=None, ge=0, le=10)
vote_count: Optional[StrictInt] = Field(default=None, ge=0)
[docs]
def paginated_movie_list(ge=1):
"""
Build the base model for a paginated movie-list response.
TMDB's list-style movie endpoints (popular, search, discover, trending)
share one envelope: a ``page`` number, a ``results`` array of
``MovieListItem`` (required non-empty here — endpoints whose empty-result
case is valid assert it directly in the test instead), and
``total_pages`` / ``total_results`` counts. Each endpoint subclasses the
returned base so it keeps a distinct, individually-registered model name
while sharing this field definition.
:param ge: Lower bound applied to the integer pagination fields
(``page``, ``total_pages``, ``total_results``). Defaults to 1;
popular passes 0 for its looser contract.
:return: A Pydantic base model class with the shared paginated fields.
"""
return create_model(
"PaginatedMovieList",
page=(StrictInt, Field(ge=ge)),
results=(list[MovieListItem], Field(min_length=1)),
total_pages=(StrictInt, Field(ge=ge)),
total_results=(StrictInt, Field(ge=ge)),
)
[docs]
class PopularMoviesResponse(paginated_movie_list(ge=0)):
"""
Schema for popular movies list response from ``GET /3/movie/popular``.
Validates the paginated response structure containing a list of
popular movies. Result items use the shared ``MovieListItem`` model.
Replaces: ``popular_movies_schema.json``
"""
[docs]
class TrendingMoviesResponse(paginated_movie_list()):
"""
Schema for trending movies list response from
``GET /3/trending/movie/{time_window}``.
Validates the paginated response structure containing the movies trending
over the requested time window (``day`` or ``week``). Result items use the
shared ``MovieListItem`` model.
"""
[docs]
class SearchMoviesResponse(paginated_movie_list()):
"""
Schema for movie search response from ``GET /3/search/movie``.
Validates the paginated response structure containing the movies that
matched a search query. Result items use ``SearchMovieListItem`` rather
than the shared ``MovieListItem`` — search results can include stub
catalog entries that omit the genre/vote/release fields, so ``results``
is redeclared here to point at the tolerant item model (Pydantic does not
merge a subclass's fields into a *nested* model, so the override must
replace the ``results`` annotation itself). ``results`` still requires
at least one item — searches expected to return no matches are asserted
directly in the test instead of via this schema.
"""
results: list[SearchMovieListItem] = Field(min_length=1)
[docs]
class DiscoverMoviesResponse(paginated_movie_list()):
"""
Schema for movie discovery response from ``GET /3/discover/movie``.
Validates the paginated response structure containing the movies that
matched the discover filter/sort criteria. Result items use the shared
``MovieListItem`` model. ``results`` requires at least one item —
filter combinations expected to match nothing are asserted directly
in the test instead of via this schema.
"""
[docs]
class PersonDetails(BaseModel):
"""
Schema for person details response from ``GET /3/person/{person_id}``.
Validates the response structure for the TMDB person details endpoint.
Uses ``extra = "allow"`` to accept additional fields not explicitly
defined here (e.g., external_ids, combined_credits).
Replaces: ``person_details_schema.json``
:param adult: Whether the person is associated with adult content.
:param also_known_as: Alternative names or aliases, or None.
:param biography: Biographical text about the person.
:param birthday: Date of birth in ``YYYY-MM-DD`` format.
:param deathday: Date of death in ``YYYY-MM-DD`` format, or None if alive.
:param gender: Gender identifier (0=not specified, 1=female, 2=male, 3=non-binary).
:param homepage: Personal website URL, or None.
:param id: Unique TMDB person identifier.
:param imdb_id: IMDb identifier (e.g., ``nm0000093``).
:param known_for_department: Primary department (e.g., "Acting", "Directing").
:param name: Full name of the person.
:param place_of_birth: City/country of birth, or None if unknown.
:param popularity: TMDB popularity score.
:param profile_path: Path to the profile image, or None.
"""
adult: StrictBool
also_known_as: list[str] # always present, may be empty
biography: StrictStr # may be empty
birthday: Optional[str] = None # null for some people
deathday: Optional[str] = None
gender: StrictInt = Field(ge=0, le=3) # 0=n/a, 1=F, 2=M, 3=non-binary
homepage: Optional[str] = None
id: StrictInt = Field(ge=0)
imdb_id: Optional[str] = None # null for some people
known_for_department: StrictStr = Field(min_length=1)
name: StrictStr = Field(min_length=1)
place_of_birth: Optional[str] = None
popularity: StrictFloat = Field(ge=0)
profile_path: Optional[str] = Field(default=None, pattern=r".*\.(png|jpg)$")
model_config = {"extra": "allow"}
[docs]
class NetworkDetails(BaseModel):
"""
Schema for network details response from ``GET /3/network/{network_id}``.
Validates the response structure for the TMDB network details endpoint.
The body is small and fully enumerated, so ``extra = "forbid"`` keeps
the contract strict.
:param headquarters: Network headquarters location, may be empty.
:param homepage: Network website URL, may be empty.
:param id: Unique TMDB network identifier.
:param logo_path: Path to the network logo image, or None.
:param name: Name of the network.
:param origin_country: ISO 3166-1 country code, may be empty (e.g., Netflix).
"""
headquarters: StrictStr # may be empty
homepage: StrictStr # may be empty
id: StrictInt = Field(ge=1)
logo_path: Optional[str] = Field(default=None, pattern=r".*\.(png|jpg)$")
name: StrictStr = Field(min_length=1)
origin_country: StrictStr # empty for some networks
model_config = {"extra": "forbid"}
# Nested model for a review's author
[docs]
class AuthorDetails(BaseModel):
"""
Nested model for the ``author_details`` block of a review.
:param name: Author's display name, may be empty.
:param username: Author's TMDB username.
:param avatar_path: Path to the author's avatar, or None. Unlike other
``*_path`` fields this is NOT constrained to an image
extension — TMDB may store a gravatar URL here
(e.g. ``/https://secure.gravatar.com/...``).
:param rating: The author's rating for the media (0–10), or None.
"""
name: StrictStr # may be empty
username: StrictStr = Field(min_length=1)
avatar_path: Optional[str] = None # may be a gravatar URL, not just an image path
rating: Optional[float] = Field(default=None, ge=0, le=10)
model_config = {"extra": "forbid"}
[docs]
class ReviewDetails(BaseModel):
"""
Schema for review details response from ``GET /3/review/{review_id}``.
Validates the response structure for the TMDB review details endpoint.
The body is small and fully enumerated, so ``extra = "forbid"`` keeps
the contract strict.
:param id: Unique TMDB review identifier (24-character hex string).
:param author: Author's display name.
:param author_details: Nested author metadata (name, username, avatar, rating).
:param content: The review text.
:param created_at: Creation timestamp (ISO 8601).
:param iso_639_1: ISO 639-1 language code of the review.
:param media_id: TMDB id of the reviewed media.
:param media_title: Title of the reviewed media.
:param media_type: Media type of the reviewed item (e.g. ``movie``).
:param updated_at: Last-updated timestamp (ISO 8601).
:param url: Public URL of the review on themoviedb.org.
"""
id: StrictStr = Field(min_length=1)
author: StrictStr = Field(min_length=1)
author_details: AuthorDetails
content: StrictStr = Field(min_length=1)
created_at: StrictStr = Field(min_length=1)
iso_639_1: StrictStr = Field(min_length=1)
media_id: StrictInt = Field(ge=0)
media_title: StrictStr = Field(min_length=1)
media_type: StrictStr = Field(min_length=1)
updated_at: StrictStr = Field(min_length=1)
url: StrictStr = Field(min_length=1)
model_config = {"extra": "forbid"}
# Nested model for a review in a movie's reviews list
[docs]
class ReviewListItem(BaseModel):
"""
Nested model for one item of the ``movie/{id}/reviews`` ``results`` array.
A list item is the subset of :class:`ReviewDetails` the reviews-list
endpoint returns — it omits the ``media_id`` / ``media_title`` /
``media_type`` fields that only the standalone ``review/{id}`` detail
endpoint carries. The nested ``author_details`` block is identical, so it
reuses :class:`AuthorDetails`.
:param author: Author's display name.
:param author_details: Nested author metadata (name, username, avatar, rating).
:param content: The review text.
:param created_at: Creation timestamp (ISO 8601).
:param id: Unique TMDB review identifier (24-character hex string).
:param updated_at: Last-updated timestamp (ISO 8601).
:param url: Public URL of the review on themoviedb.org.
"""
author: StrictStr = Field(min_length=1)
author_details: AuthorDetails
content: StrictStr = Field(min_length=1)
created_at: StrictStr = Field(min_length=1)
id: StrictStr = Field(min_length=1)
updated_at: StrictStr = Field(min_length=1)
url: StrictStr = Field(min_length=1)
model_config = {"extra": "forbid"}
[docs]
class MovieReviewsResponse(BaseModel):
"""
Schema for a movie's reviews list from ``GET /3/movie/{movie_id}/reviews``.
Unlike the paginated *movie*-list endpoints, this envelope also carries a
top-level ``id`` (the movie whose reviews these are) alongside the usual
``page`` / ``results`` / ``total_pages`` / ``total_results`` fields, and its
``results`` are reviews, not movies. That distinct result type is why this
is a standalone model and does **not** subclass
:func:`paginated_movie_list`. ``results`` requires at least one item — the
reviews journey only validates against this schema for a movie that actually
has reviews, asserting the empty case directly instead.
:param id: TMDB id of the movie the reviews belong to.
:param page: Current page number.
:param results: List of reviews on this page.
:param total_pages: Total number of review pages.
:param total_results: Total number of reviews across all pages.
"""
id: StrictInt = Field(ge=0)
page: StrictInt = Field(ge=1)
results: list[ReviewListItem] = Field(min_length=1)
total_pages: StrictInt = Field(ge=1)
total_results: StrictInt = Field(ge=1)