# -*- coding: utf-8 -*- """ tmdbsimple.discover ~~~~~~~~~~~~~~~~~~~ This module implements the Discover functionality of tmdbsimple. Created by Celia Oakley on 2013-10-31. :copyright: (c) 2013-2020 by Celia Oakley :license: GPLv3, see LICENSE for more details """ from .base import TMDB class Discover(TMDB): """ Discover functionality. See: https://developers.themoviedb.org/3/discover """ BASE_PATH = 'discover' URLS = { 'movie': '/movie', 'tv': '/tv', } def movie(self, **kwargs): """ Discover movies by different types of data like average rating, number of votes, genres and certifications. You can get a valid list of certifications from the certifications list method. Discover also supports a nice list of sort options. See below for all of the available options. Please note, when using certification / certification.lte you must also specify certification_country. These two parameters work together in order to filter the results. You can only filter results with the countries we have added to our certifications list. If you specify the region parameter, the regional release date will be used instead of the primary release date. The date returned will be the first date based on your query (ie. if a with_release_type is specified). It's important to note the order of the release types that are used. Specifying "2|3" would return the limited theatrical release date as opposed to "3|2" which would return the theatrical date. Also note that a number of filters support being comma (,) or pipe (|) separated. Comma's are treated like an AND and query while pipe's are an OR. Some examples of what can be done with discover can be found at https://www.themoviedb.org/documentation/api/discover. Args: page: (optional) Minimum 1, maximum 1000. language: (optional) ISO 639-1 code. sort_by: (optional) Available options are 'vote_average.desc', 'vote_average.asc', 'release_date.desc', 'release_date.asc' 'popularity.desc', 'popularity.asc'. include_adult: (optional) Toggle the inclusion of adult titles. Expected value is a boolean, True or False. year: (optional) Filter the results release dates to matches that include this value. Expected value is a year. primary_release_year: (optional) Filter the results so that only the primary release date year has this value. Expected value is a year. vote_count.gte or vote_count_gte: (optional) Only include movies that are equal to, or have a vote count higher than this value. Expected value is an integer. vote_average.gte or vote_average_gte: (optional) Only include movies that are equal to, or have a higher average rating than this value. Expected value is a float. with_genres: (optional) Only include movies with the specified genres. Expected value is an integer (the id of a genre). Multiple values can be specified. Comma separated indicates an 'AND' query, while a pipe (|) separated value indicates an 'OR'. release_date.gte or release_date_gte: (optional) The minimum release to include. Expected format is 'YYYY-MM-DD'. releaste_date.lte or release_date_lte: (optional) The maximum release to include. Expected format is 'YYYY-MM-DD'. certification_country: (optional) Only include movies with certifications for a specific country. When this value is specified, 'certification.lte' is required. An ISO 3166-1 is expected. certification.lte or certification_lte: (optional) Only include movies with this certification and lower. Expected value is a valid certification for the specified 'certification_country'. with_companies: (optional) Filter movies to include a specific company. Expected value is an integer (the id of a company). They can be comma separated to indicate an 'AND' query. Returns: A dict respresentation of the JSON returned from the API. """ # Periods are not allowed in keyword arguments but several API # arguments contain periods. See both usages in tests/test_discover.py. for param in dict(kwargs): if '_lte' in param: kwargs[param.replace('_lte', '.lte')] = kwargs.pop(param) if '_gte' in param: kwargs[param.replace('_gte', '.gte')] = kwargs.pop(param) path = self._get_path('movie') response = self._GET(path, kwargs) self._set_attrs_to_values(response) return response def tv(self, **kwargs): """ Discover TV shows by different types of data like average rating, number of votes, genres, the network they aired on and air dates. Discover also supports a nice list of sort options. See below for all of the available options. Also note that a number of filters support being comma (,) or pipe (|) separated. Comma's are treated like an AND and query while pipe's are an OR. Some examples of what can be done with discover can be found at https://www.themoviedb.org/documentation/api/discover. Args: page: (optional) Minimum 1, maximum 1000. language: (optional) ISO 639-1 code. sort_by: (optional) Available options are 'vote_average.desc', 'vote_average.asc', 'first_air_date.desc', 'first_air_date.asc', 'popularity.desc', 'popularity.asc' first_air_year: (optional) Filter the results release dates to matches that include this value. Expected value is a year. vote_count.gte or vote_count_gte: (optional) Only include TV shows that are equal to, or have vote count higher than this value. Expected value is an integer. vote_average.gte or vote_average_gte: (optional) Only include TV shows that are equal to, or have a higher average rating than this value. Expected value is a float. with_genres: (optional) Only include TV shows with the specified genres. Expected value is an integer (the id of a genre). Multiple valued can be specified. Comma separated indicates an 'AND' query, while a pipe (|) separated value indicates an 'OR'. with_networks: (optional) Filter TV shows to include a specific network. Expected value is an integer (the id of a network). They can be comma separated to indicate an 'AND' query. first_air_date.gte or first_air_date_gte: (optional) The minimum release to include. Expected format is 'YYYY-MM-DD'. first_air_date.lte or first_air_date_lte: (optional) The maximum release to include. Expected format is 'YYYY-MM-DD'. Returns: A dict respresentation of the JSON returned from the API. """ # Periods are not allowed in keyword arguments but several API # arguments contain periods. See both usages in tests/test_discover.py. for param in dict(kwargs): if '_lte' in param: kwargs[param.replace('_lte', '.lte')] = kwargs.pop(param) if '_gte' in param: kwargs[param.replace('_gte', '.gte')] = kwargs.pop(param) path = self._get_path('tv') response = self._GET(path, kwargs) self._set_attrs_to_values(response) return response