API Module

Account API

class api.account_api.AccountAPI

Bases: BaseAPI

get_rated_movies(session_id, query_params=None)

Retrieve a paginated list of movies rated by the user.

Parameters:

  • session_id – Optional path parameter (e.g., account ID).

  • query_params – Optional dict of query parameters. Defaults to page 1 if not specified.

Returns:

Response object with paginated list of rated movies.

Base API

Base API Module

This module provides the foundation for all API interactions with the Movie Database.

class api.base_api.APIResponse(data: dict, status_code: int, url: str, headers: Any, cookies: Any, encoding: str, elapsed_seconds: float = 0.0, reason: str = '', request: str = '', request_params: dict | None = None, request_payload: dict | None = None)

Bases: object

cookies: Any
data: dict
elapsed_seconds: float = 0.0
encoding: str
headers: Any
reason: str = ''
request: str = ''
request_params: dict | None = None
request_payload: dict | None = None
status_code: int
url: str
class api.base_api.BaseAPI

Bases: object

Base API client providing common HTTP methods.

This class handles authentication, session management, and HTTP operations for interacting with the Movie Database API.

Variables:

  • base_url – The base URL for API requests.

  • headers – Default headers including authentication.

  • session – Persistent requests session.

delete(endpoint, data=None, params=None)

Perform a DELETE request to the specified endpoint.

Parameters:

  • endpoint (str) – API endpoint path.

  • data (dict, optional) – Optional data payload to send in the request body.

  • params (dict, optional) – Optional query parameters.

Returns:

API response with data, status code, and metadata.

Return type:

APIResponse

get(endpoint, params=None)

Perform a GET request to the specified endpoint.

Parameters:

  • endpoint (str) – API endpoint path.

  • params (dict, optional) – Optional query parameters.

Returns:

API response with data, status code, and metadata.

Return type:

APIResponse

post(endpoint, json=None, params=None)

Perform a POST request to the specified endpoint.

Parameters:

  • endpoint (str) – API endpoint path.

  • json (dict, optional) – JSON payload to send in the request body.

  • params (dict, optional) – Optional query parameters.

Returns:

API response with data, status code, and metadata.

Return type:

APIResponse

put(endpoint, data=None)

Perform a PUT request to the specified endpoint.

Parameters:

  • endpoint (str) – API endpoint path.

  • data (dict, optional) – Optional JSON payload to send in the request body.

Returns:

API response with data, status code, and metadata.

Return type:

APIResponse

Lists API

class api.lists_api.ListsAPI

Bases: BaseAPI

Client for TMDB Lists API endpoints.

Provides methods for creating, updating, deleting lists, and managing list items. All methods return a response object containing status code, headers, and parsed data.

Attributes:

_sub_path (str): Base path segment for list endpoints.

Example:

api = ListsAPI() new_list = api.create_list(name=”My Favorite Movies”, description=”A list of my favorite movies”, language=”en”)

update_list(list_id, payload)

Update an existing list’s metadata details.

Parameters:

  • list_id – TMDB list ID to update.

  • payload – Dict containing fields to update (e.g., name, description).

Returns:

Response object with updated list details.

Movies API

Movies API client for The Movie Database (TMDB) endpoints.

This module provides a high-level interface for interacting with movie-related TMDB API endpoints. It extends BaseAPI to inherit authentication, request handling, and response parsing functionality.

Usage:

api = MoviesAPI() response = api.get_movie_details(550) # Get Fight Club details logger.info(response.data[‘title’])

class api.movies_api.MoviesAPI

Bases: BaseAPI

Client for TMDB Movies API endpoints.

Provides methods for retrieving movie details, popular movies, top-rated movies, and alternative titles. All methods return a response object containing status code, headers, and parsed data.

Attributes:

_sub_path (str): Base path segment for movie endpoints.

Example:

api = MoviesAPI() movie = api.get_movie_details(550) popular = api.get_popular_movies({‘page’: 2})

add_rating(movie_id, rating, query_params=None)

Add a user rating for a specific movie.

Parameters:

  • movie_id – TMDB movie ID.

  • rating – User rating value (0.5 to 10.0).

  • query_params – Optional dict of query parameters, such as session_id for authentication.

Returns:

Response object with status of the rating submission.

delete_rating(movie_id, query_params=None)

Delete a user rating for a specific movie. :param movie_id: TMDB movie ID. :param query_params: Optional dict of query parameters, such as session_id for authentication. :return: Response object with status of the rating deletion.

get_alt_title(movie_id)

Retrieve alternative titles for a specific movie.

Returns localized and regional title variations for the movie.

Parameters:

movie_id – TMDB movie ID.

Returns:

Response object with list of alternative titles including country codes and title strings.

get_movie_details(movie_id)

Retrieve detailed information for a specific movie.

Parameters:

movie_id – TMDB movie ID (e.g., 550 for Fight Club).

Returns:

Response object with movie details including title, genres, production companies, and release info.

get_popular_movies(query_params=None)

Retrieve a paginated list of currently popular movies.

Parameters:

query_params – Optional dict of query parameters. Defaults to page 1 if not specified.

Returns:

Response object with paginated list of popular movies.

get_top_rated(query_params=None)

Retrieve a paginated list of top-rated movies.

Parameters:

query_params – Optional dict of query parameters. Defaults to page 1 if not specified.

Returns:

Response object with paginated list of top-rated movies.

People API

class api.people_api.PeopleAPI

Bases: BaseAPI

Client for TMDB People API endpoints.

Provides methods for retrieving person details, popular people, and top-rated people. All methods return a response object containing status code, headers, and parsed data.

Attributes:

_sub_path (str): Base path segment for people endpoints.

get_person_details(person_id)

Retrieve detailed information for a specific person.

Parameters:

person_id – TMDB person ID (e.g., 287 for Brad Pitt).

Returns:

Response object with person details including name, biography, known for movies, and birth info.