tmdb3 0.6.17

TheMovieDB.org APIv3 interface

## PyTMDB3

This Python module implements the v3 API for TheMovieDb.org, allowing access to movie and cast information, as well as related artwork. More information can be found at:

http://help.themoviedb.org/kb/api/about-3

## Initial Access

Access to the API requires a personal key. You can create one by signing up for an account on TheMovieDb.org, and generating one from your Account Details page. Once done, the PyTMDB3 module must be be given this key as follows:

>>> from tmdb3 import set_key
>>> set_key('your_api_key')

## Caching Engine

In order to limit excessive usage against the online API server, the PyTMDB3 module supports caching of requests. Cached data is keyed off the request URL, and is currently stored for one hour. This may get tuned further as the v3 API gets increased usage, and official limits are set per host.

There are currently two engines available for use. The ‘null’ engine merely discards all information, and is only intended for debugging use. The ‘file’ engine is defualt, and will store to ‘/tmp/pytmdb3.cache’ unless configured otherwise. The cache engine can be configured as follows.

>>> from tmdb3 import set_cache
>>> set_cache('null')
>>> set_cache(filename='/full/path/to/cache') # the 'file' engine is assumed
>>> set_cache(filename='tmdb3.cache')         # relative paths are put in /tmp
>>> set_cache(engine='file', filename='~/.tmdb3cache')

## Locale Configuration

The previous v2 API supported language selection, but would fall through to the defaults for any fields that did not have language-specific values. The v3 API no longer performs this fall through, leaving it up to clients to optionally implement it on their own.

The PyTMDB3 module supports the use of locales in two separate manners. One can define a global locale that is automatically used if not specified otherwise, or a specific locale can be supplied directly to searches and data queries using the ‘locale=’ keyword argument, which is then propogated through any subsequent queries made through those objects.

Locale settings are controlled through two functions

>>> from tmdb3 import get_locale, set_locale
>>> get_locale()
<Locale None_None>
>>> set_locale()
>>> get_locale()
<Locale en_US>
>>> set_locale('en', 'gb')
>>> get_locale()
<Locale en_GB>
>>> get_locale('fr', 'fr')
<Locale fr_FR>

set_locale() is used to set the global default locale. It optionally accepts ‘language’ and ‘country’ keyword arguments. If not supplied, it will attempt to pull such information from your environment. It also accepts a ‘fallthrough’ keyword argument, which is used to control the language and country filter fall through. This is disabled by default, meaning if a language is set, it will only return information specific to that language.

get_locale() also accepts optional ‘language’ and ‘country’ keyword arguments, and can be used to generate locales to use directly, overriding the global configuration. If none are given, this instead returns the global configuration. Note that fall through behavior is applied module-wide, and individual locales cannot be used to change that behavior.

## Authentication

This is not yet supported.

## Searching

There are currently three search methods available for use: movies, people, studios, lists, and collections. Search results from TheMovieDb are sent iteratively, twenty results per page. The search methods provided by the PyTMDB3 module return list-like structures that will automatically grab new pages as needed.

>>> from tmdb3 import searchMovie
>>> res = searchMovie('A New Hope')
>>> res
<Search Results: A New Hope>
>>> len(res)
4
>>> res[0]
<Movie 'Star Wars: Episode IV - A New Hope' (1977)>

The movieSearch() method accepts an ‘adult’ keyword to allow adult content to be returned. By default, this is set to false and such content is filtered out. The people search method behaves similarly.

>>> from tmdb import searchPerson
>>> res = searchPerson('Hanks')
>>> res
<Search Results: Hanks>
>>> res[0]
<Person 'Tom Hanks'>

>>> from tmdb import searchStudio
>>> res = searchStudio('Sony Pictures')
>>> res
<Search Results: Sony Pictures>
>>> res[0]
<Studio 'Sony Pictures'>

The movieSearch() method accepts a ‘year’ keyword, tell tell TMDB to filter for movies of only that specific year. There is a helper method, movieSearchWithYear(), which will process the release year from movie names where the year is contained in parentheses, as in:

>>> from tmdb import searchMovieWithYear
>>> list(searchMovieWithYear('Star Wars (1977)'))
[<Movie 'Star Wars: Episode IV - A New Hope' (1977)>,
              <Movie 'The Making of 'Star Wars'' (1977)>]

## Direct Queries

There are currently four data types that support direct access: collections, movies, people, and studios. These each take a single integer ID as an argument. All data attributes are implemented as properties, and populated on-demand as used, rather than when the object is created.

>>> from tmdb3 import Collection, Movie, Person, Studio
>>> Collection(10)
<Collection 'Star Wars Collection'>
>>> Movie(11)
<Movie 'Star Wars: Episode IV - A New Hope' (1977)>
>>> Person(2)
<Person 'Mark Hamill'>
>>> Studio(1)
<Studio 'Lucasfilm'>

The Genre class cannot be called by id directly, however it does have a getAll classmethod, capable of returning all available genres for a specified language.

## Image Behavior

TheMovieDb currently offers three types of artwork: backdrops, posters, and profiles. The three data queries above will each carry a default one of these and potentially a list of additionals to choose from. Each can be downloaded directly, or at one of several pre-scaled reduced resolutions. The PyTMDB3 module provides a list of list of available sizes, and will generate a URL to download a requested size. Invalid sizes return an error

>>> from tmdb3 import Movie
>>> p = Movie(11).poster
>>> p
<Poster 'tvSlBzAdRE29bZe5yYWrJ2ds137.jpg'>
>>> p.sizes()
[u'w92', u'w154', u'w185', u'w342', u'w500', u'original']
>>> p.geturl()
u'http://cf2.imgobject.com/t/p/original/tvSlBzAdRE29bZe5yYWrJ2ds137.jpg'
>>> p.geturl('w342')
u'http://cf2.imgobject.com/t/p/w342/tvSlBzAdRE29bZe5yYWrJ2ds137.jpg'
>>> p.geturl('w300')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "tmdb3/tmdb_api.py", line 101, in geturl
    raise TMDBImageSizeError
tmdb3.tmdb_exceptions.TMDBImageSizeError: None

## Trailers

TheMovieDb offers access to trailers on Youtube and Apple, however their use is slightly different. Youtube trailers offer an individual file, while Apple trailers offer multiple sizes.

>>> from tmdb3 import Movie
>>> movie = Movie(27205)
>>> movie.youtube_trailers
[<YoutubeTrailer 'Trailer 1'>, <YoutubeTrailer 'Trailer 2'>]
>>> movie.youtube_trailers[0].geturl()
'http://www.youtube.com/watch?v=suIIHZqDR30'
>>> movie.apple_trailers
[<AppleTrailer 'Teaser'>, <AppleTrailer 'Trailer 1'>, <AppleTrailer 'Trailer 2'>]
>>> movie.apple_trailers[0].sizes()
[u'480p', u'720p', u'1080p']
>>> movie.apple_trailers[0].geturl()
u'http://pdl.warnerbros.com/wbmovies/inception/Inception_TRL1_1080.mov'
>>> movie.apple_trailers[0].geturl()
u'http://pdl.warnerbros.com/wbmovies/inception/Inception_TRL1_480.mov'

## List of Available Data

type name

Collection:

integer id string name string overview Backdrop backdrop Poster poster list(Movie) members list(Backdrop) backdrops list(Poster) posters

Movie:

integer id string title (language specific) string originaltitle (origin language) string tagline string overview integer runtime integer budget integer revenue datetime releasedate string homepage string IMDB reference id (‘ttXXXXXXX’) Backdrop backdrop Poster poster float popularity float userrating integer votes boolean adult Collection collection list(Genre) genres list(Studio) studios list(Country) countries list(Language) languages list(AlternateTitle) alternate_titles list(Cast) cast (sorted by billing) list(Crew) crew list(Backdrop) backdrops list(Poster) posters list(Keyword) keywords dict(Release) releases (indexed by country) list(Translation) translations list(Movie) similar list(List) lists list(Movie) getSimilar() None setFavorite(bool) mark favorite status for current user None setRating(int) rate movie by current user None setWatchlist(bool) mark watchlist status for current user

Movie classmethods:

Movie fromIMDB(imdbid) special constructor for use with IMDb codes Movie latest() gets latest movie added to database list(Movie) nowplaying() content currently in theater list(Movie) mostpopular() based off themoviedb.org page view counts list(Movie) toprated() based off themoviedb.org user ratings list(Movie) upcoming() curated list, typically contains 100 movies list(Movie) favorites() current user’s favorite movies list(Movie) ratedmovies() movies rated by current user list(Movie) watchlist() movies marked to watch by current user

List:

hex string id string name string author string description integer favorites number of users that have marked list string language integer count Poster poster list(Movie) members

Person:

integer id string name string biography datetime dayofbirth datetime dayofdeath string homepage Profile profile boolean adult list(string) aliases list(ReverseCast) roles list(ReverseCrew) crew list(Profile) profiles

Cast (derived from Person):

string character integer order (as appears in credits)

Crew (derived from Person):

string job string department

ReverseCast (derived from Movie):

string character

ReverseCrew (derived from Movie):

string job string department

Image:

string filename (arbitrary alphanumeric code) float aspectratio (not available for default images) integer height (not available for default images) integer width (not available for default images) integer language (not available for default images) float userrating integer votes list(string) sizes() string geturl(size=’original’)

Backdrop (derived from Image) Poster (derived from Image) Profile (derived from Image) Logo (derived from Image)

AlternateTitle:

string country string title

Release:

string certification string country datetime releasedate

Translation:

string name string englishname string language

Genre:

integer id string name list(Movie) movies

Genre classmethods:

list(Genre) getAll(language) returns list of all genres

Studio:

integer id string name string description string headquarters Logo logo Studio parent list(Movie) movies

Country:

string code string name

Language:

string code string name

Trailer:

string name string size string source

YoutubeTrailer (derived from Trailer)

string geturl()

AppleTrailer

string name dict(Trailer) sources (indexed by size) list(string) sizes() string geturl(size=None)