Source code for api.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'])
"""

from loguru import logger
from api.base_api import BaseAPI

[docs] class MoviesAPI(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}) """ _sub_path = "movie"
[docs] def get_movie_details(self, movie_id): """ Retrieve detailed information for a specific movie. :param movie_id: TMDB movie ID (e.g., 550 for Fight Club). :return: Response object with movie details including title, genres, production companies, and release info. Example ``response.data``:: { "adult": false, "id": 550, "title": "Fight Club", "original_title": "Fight Club", "original_language": "en", "release_date": "1999-10-15", "origin_country": ["US"], "genres": [{"id": 18, "name": "Drama"}], "production_companies": [ {"id": 508, "logo_path": "/7cxRWzi4LsVm4Utfpr1hfARNurT.png", "name": "Regency Enterprises", "origin_country": "US"} ] } """ return self.get(f"{self._sub_path}/{movie_id}")
[docs] def get_top_rated(self, query_params=None): """ Retrieve a paginated list of top-rated movies. :param query_params: Optional dict of query parameters. Defaults to page 1 if not specified. :return: Response object with paginated list of top-rated movies. Example ``response.data``:: { "page": 1, "results": [ {"id": 278, "title": "The Shawshank Redemption", "original_language": "en", "vote_average": 8.7, "vote_count": 27000, "release_date": "1994-09-23"} ], "total_pages": 500, "total_results": 10000 } """ query_params ={ 'page': 1 , **(query_params or {})} return self.get(f"{self._sub_path}/top_rated", params=query_params)
[docs] def get_movie_reviews(self, movie_id, query_params=None): """ Retrieve user reviews for a specific movie. :param movie_id: TMDB movie ID. :param query_params: Optional dict of query parameters (e.g., page). :return: Response object with a paginated list of user reviews. Example ``response.data``:: { "id": 550, "page": 1, "results": [ {"id": "5b1c13b9c3a36848f2026384", "author": "Cat Ellington", "author_details": {"name": "Cat Ellington", "username": "CatEllington", "avatar_path": null, "rating": 8.0}, "content": "The film that launched...", "created_at": "2018-06-09T18:15:37.023Z", "updated_at": "2021-06-23T15:58:09.043Z", "url": "https://www.themoviedb.org/review/5b1c13b9c3a36848f2026384"} ], "total_pages": 1, "total_results": 8 } """ logger.debug(f"query_params: {query_params}") return self.get(f"{self._sub_path}/{movie_id}/reviews", params=query_params)
[docs] def get_alt_title(self, movie_id): """ Retrieve alternative titles for a specific movie. Returns localized and regional title variations for the movie. :param movie_id: TMDB movie ID. :return: Response object with list of alternative titles including country codes and title strings. Example ``response.data``:: { "id": 550, "titles": [ {"iso_3166_1": "BR", "title": "Clube da Luta", "type": ""}, {"iso_3166_1": "PL", "title": "Podziemny krąg", "type": ""} ] } """ return self.get(f"{self._sub_path}/{movie_id}/alternative_titles")
[docs] def add_rating(self, movie_id, rating, query_params=None): """ Add a user rating for a specific movie. :param movie_id: TMDB movie ID. :param rating: User rating value (0.5 to 10.0). :param query_params: Optional dict of query parameters, such as session_id for authentication. :return: Response object with status of the rating submission. Example ``response.data``:: {"success": true, "status_code": 1, "status_message": "Success."} """ payload = {'value': rating} return self.post(f"{self._sub_path}/{movie_id}/rating", params=query_params, json=payload)
[docs] def delete_rating(self, 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. Example ``response.data``:: {"success": true, "status_code": 13, "status_message": "The item/record was deleted successfully."} """ return self.delete(f"{self._sub_path}/{movie_id}/rating", params=query_params)