aTMDb package¶

client module¶

API client wrapper.

class atmdb.client.TMDbClient(*, api_token=None, **kwargs)[source]¶

Bases: atmdb.core.UrlParamMixin, atmdb.core.Service

Simple wrapper for the TMDb API.

config_expired¶

Whether the configuration data has expired.

find_movie(query)[source]¶

Retrieve movie data by search query.

Parameters:	query (str) – Query to search for.
Returns:	Possible matches.
Return type:	list

find_person(query)[source]¶

Retrieve person data by search query.

Parameters:	query (str) – Query to search for.
Returns:	Possible matches.
Return type:	list

get_data(url)[source]¶

Get data from the TMDb API via aiohttp.get().

Notes

Updates configuration (if required) on successful requests.

Parameters:	url (str) – The endpoint URL and params.
Returns:	The parsed JSON result.
Return type:	dict

get_movie(id_)[source]¶

Retrieve movie data by ID.

Parameters:	id (int) – The movie’s TMDb ID.
Returns:	The requested movie.
Return type:	Movie

get_person(id_)[source]¶

Retrieve person data by ID.

Parameters:	id (int) – The person’s TMDb ID.
Returns:	The requested person.
Return type:	Person

get_random_popular_person(limit=500)[source]¶

Randomly select a popular person.

Notes

Requires at least two API calls. May require three API calls if the randomly-selected index isn’t within the first page of required data.

Parameters:	limit (int, optional) – How many of the most popular people to make random choice from (defaults to top 500).
Returns:	A randomly-selected popular person.
Return type:	Person

core module¶

Core API wrapper functionality, adapted from Flash Services.

class atmdb.core.Service(*_, **kwargs)[source]¶

Bases: object

Abstract base class for API wrapper services.

REQUIRED = set()¶

set – The service’s required configuration keys.

ROOT = ''¶

str – The root URL for the API.

static calculate_timeout(http_date)[source]¶

Extract request timeout from e.g. Retry-After header.

Notes

Per RFC 2616#section-14.37, the Retry-After header can be either an integer number of seconds or an HTTP date. This function can handle either.

Parameters:	http_date (str) – The date to parse.
Returns:	The timeout, in seconds.
Return type:	int

headers¶

Get the headers for the service requests.

Returns:	The header mapping.
Return type:	dict

url_builder(endpoint, *, root=None, params=None, url_params=None)[source]¶

Create a URL for the specified endpoint.

Parameters:	endpoint (str) – The API endpoint to access. root – (str, optional): The root URL for the service API. params – (dict, optional): The values for format into the created URL (defaults to None). url_params – (dict, optional): Parameters to add to the end of the URL (defaults to None).
Returns:	The resulting URL.
Return type:	str

class atmdb.core.TokenAuthMixin(*, api_token, **kwargs)[source]¶

Bases: object

Mix-in class for implementing token authentication.

Parameters:	api_token (str) – A valid API token.

TOKEN_ENV_VAR = None¶

str – The environment variable holding the token.

classmethod from_env()[source]¶

Create a service instance from an environment variable.

class atmdb.core.UrlParamMixin(*, api_token, **kwargs)[source]¶

Bases: atmdb.core.TokenAuthMixin

Mix-in class for implementing URL parameter authentication.

AUTH_PARAM = None¶

str – The name of the URL parameter.

url_builder(endpoint, params=None, url_params=None)[source]¶

Add authentication URL parameter.

models module¶

Models representing TMDb resources.

class atmdb.models.BaseModel(*, id_, image_path=None, **_)[source]¶

Bases: object

Base TMDb model functionality.

Parameters:	id (int) – The TMDb ID of the object. image_path (str) – The short path to the image.

image_url¶

str – The fully-qualified image URL.

CONTAINS = None¶

dict – Rules for what the model contains.

IMAGE_TYPE = None¶

str – The type of image to use.

JSON_MAPPING = {'id_': 'id'}¶

dict – The mapping between JSON keys and attributes.

classmethod from_json(json, image_config=None)[source]¶

Create a model instance

Parameters:	json (dict) – The parsed JSON data. image_config (dict) – The API image configuration data.
Returns:	The model instance.
Return type:	BaseModel

image_config = None¶

dict – The API image configuration.

class atmdb.models.Movie(*, title, cast=None, synopsis=None, release_date=None, **kwargs)[source]¶

Bases: atmdb.models.BaseModel

Represents a movie.

Parameters:	title (str) – The title of the movie. cast (set, optional) – The movie’s cast. synopsis (str, optional) – A synopsis of the movie. release_date (datetime.date) – The date of release.

release_year¶

int

url¶

str – The URL to the movies’s TMDb page.

class atmdb.models.Person(name, biography=None, movie_credits=None, known_for=None, birthday=None, deathday=None, **kwargs)[source]¶

Bases: atmdb.models.BaseModel

Represents a person.

Parameters:	name (str) – The person’s name. movie_credits (set, optional) – The person’s movie credits. biography (str, optional) – A synopsis of the movie. known_for (list, optional) – A list of the three movies the person is best known for. birthday (datetime.date, optional) – The person’s date of birth. birthday – The person’s date of death.

age¶

int – The person’s age, in years (if they have died, their age at the time of their death).

alive¶

bool – Whether the person is currently alive.

url¶

str – The URL to the person’s TMDb profile.

utils module¶

Utilities for working with TMDb models.

atmdb.utils.find_overlapping_actors(titles, client)[source]¶

Find actors that have been in the same movies.

Warning

This function requires two API calls per title submitted, plus one API call per overlapping person in the result; it is therefore relatively slow.

Parameters:	titles (collections.abc.Sequence) – The titles of the movies to find overlapping actors for. client (TMDbClient) – The TMDb client.
Returns:	The relevant Person objects.
Return type:	list

atmdb.utils.find_overlapping_movies(names, client)[source]¶

Find movies that the same people have been in.

Warning

This function requires two API calls per name submitted, plus one API call per overlapping movie in the result; it is therefore relatively slow.

Parameters:	names (collections.abc.Sequence) – The names of the people to find overlapping movies for. client (TMDbClient) – The TMDb client.
Returns:	The relevant Movie objects.
Return type:	list

atmdb.utils.overlapping_actors(movies, client=None)[source]¶

Find actors that appear in the same movies.

Parameters:	movies (collections.abc.Sequence) – The Movie objects to find overlapping actors for. client (TMDbClient, optional) – The TMDb client to extract additional information about the overlap.
Returns:	The relevant Person objects.
Return type:	list

atmdb.utils.overlapping_movies(people, client=None)[source]¶

Find movies that the same people have been in.

Parameters:	people (collections.abc.Sequence) – The Person objects to find overlapping movies for. client (TMDbClient, optional) – The TMDb client to extract additional information about the overlap.
Returns:	The relevant Movie objects.
Return type:	list