6.3. Howdy Movie API
This document describes the lower level Howdy TMDB API, upon which get_mov_tor and howdy_movie_totgui are built. It lives in howdy.movie
.
6.3.1. howdy.movie module
This module implements the lower-level functionality that does the following:
Stores and retrieves the TMDB API key.
Creates two configuration singletons,
TMDBEngine
andTMDBEngineSimple
, that contain movie genre information from the TMDB database.
- class howdy.movie.TMDBEngine(verify=True)
The singleton class that, once called, initializes movie genre information from the TMDB database. This object can then be accessed to find TMDB database genre IDs from genres or vice-versa. This also loads in all TTF fonts located in the
resources
directory.See also
- class __TMDBEngine(verify=True)
This object is only instantiated once. It implements mappings between TMDB API genre IDs and genre names (horror, comedy, etc.) and loads all TTF fonts from the
resources
subdirectory.- Parameters:
verify (bool) – optional argument, whether to verify SSL connections. Default is
True
.
- getGenreFromGenreId(genre_id)
- getGenreIdFromGenre(genre)
- class howdy.movie.TMDBEngineSimple(verify=True)
The singleton class that, once called, initializes movie genre information from the TMDB database. This object can then be accessed to find TMDB database genre IDs from genres or vice-versa. Unlike
TMDBEngine
, this also does not contain the TMDB API key.See also
- class __TMDBEngine(verify=True)
This object is only instantiated once. It implements mappings between TMDB API genre IDs and genre names (horror, comedy, etc.).
- Parameters:
verify (bool) – optional argument, whether to verify SSL connections. Default is
True
.
- getGenreFromGenreId(genre_id)
- getGenreIdFromGenre(genre)
6.3.2. howdy.movie.movie module
This module contains the main back-end functionality used by the get_mov_tor and howdy_movie_totgui, and other functionalities that are used by methods in the Howdy TV API. Here are the main features of this module.
Retrieving TV show information using the TMDB database.
Getting comprehensive movie information.
- howdy.movie.movie.createProcessedMovieData(results, year=None, verify=True)
Takes the
list
of raw movie data (one row per movie) produced by TMDB, and then processes each row in the following way.If a year is specified in this method, then reject any movie that has not been aired that year.
Takes the
str
release date that TMDB produces by default, and converts that into adate
.Fixes up the
vote_average
value for the movie.Tries to find the IMDB ID for a movie.
- Parameters:
- Returns:
the post-processed and filtered
list
of movies with fixed and extra data.- Return type:
- howdy.movie.movie.getMovieData(year, genre_id, verify=True)
This returns all the movies found by TMDB in a given year, of a given TMDB genre ID.
- Parameters:
year (int) – the year on which to search.
genre_id (int) –
the TMDB genre ID. The mapping of TMDB genre ID to genre is,
{12: 'Adventure', 14: 'Fantasy', 16: 'Animation', 18: 'Drama', 27: 'Horror', 28: 'Action', 35: 'Comedy', 36: 'History', 37: 'Western', 53: 'Thriller', 80: 'Crime', 99: 'Documentary', 878: 'Science Fiction', 9648: 'Mystery', 10402: 'Music', 10749: 'Romance', 10751: 'Family', 10752: 'War', 10770: 'TV Movie'}
If
genre_id
is-1
, then ALL movies (of all genres) are chosen.verify (bool) – optional argument, whether to verify SSL connections. Default is
False
.
- Returns:
- Return type:
Warning
This method can take an arbitrary long time to run. The author has seen this method take \(\ge 600\) seconds in some instances. One should be careful when testing this functionality.
- howdy.movie.movie.get_actor_ids_dict(actor_names, verify=True)
Returns a
dict
of actor names to their TMDB actor ID.- Parameters:
- Returns:
a
dict
, where the key is the actor name and its value is the TMDB actor ID. For example, if we want to get the ids for Steve Martin and Richard Pryor,{'Richard Pryor': 9309, 'Steve Martin': 67773}
If no actors can be found, then returns an empty dictionary.
See also
- howdy.movie.movie.get_cast_and_crew(tmdb_id, num_actors=3, verify=True)
Gets the top
num_actors
, director, and producer for the movie specified by its TMDB ID.- Parameters:
- Returns:
a
dict
containing the topnum_actors
main actors, producers, and director of the movie. For example, the movie Novocaine (2001) hastmdb_id = 20794
. This returns the following information,{ 'actors' : [ 'Steve Martin', 'Laura Dern', 'Helena Bonham Carter' ], 'producers' : [ 'Daniel M. Rosenberg', 'Paul Mones' ], 'director' : 'David Atkins' }
- Return type:
- howdy.movie.movie.get_episodes_series_tmdb(tv_id, verify=True)
Returns a
list
of episodes from the TMDB database for a TV show. Otherwise returnsNone
if cannot be found.- Parameters:
- Returns:
a
list
of episodes for this TV show, ordered by air date. Each element is a summary of an episode with the following keys.airedSeason
is the season the episode aired.airedEpisodeNumber
is the order in the season that the episode aired.firstAired
is astr
representation, in the format “YYYY-MM-DD”, when the episode aired.overview
is a plot summary of the episode.
For example, for The Simpsons,
[{'airedSeason': 1, 'airedEpisodeNumber': 1, 'firstAired': '1989-12-17', 'episodeName': 'Simpsons Roasting on an Open Fire', 'overview': "When his Christmas bonus is cancelled..."}, {'airedSeason': 1, 'airedEpisodeNumber': 2, 'firstAired': '1990-01-14', 'episodeName': 'Bart the Genius', 'overview': "After switching IQ tests with Martin, Bart..."}, {'airedSeason': 1, 'airedEpisodeNumber': 3, 'firstAired': '1990-01-21', 'episodeName': "Homer's Odyssey", 'overview': 'Homer is fired for nearly causing a meltdown...'}, {'airedSeason': 1, 'airedEpisodeNumber': 4, 'firstAired': '1990-01-28', 'episodeName': "There's No Disgrace Like Home", 'overview': 'After an embarrassing experience at the company picnic...'} ... ]
- Return type:
See also
- howdy.movie.movie.get_genre_movie(title, year=None, checkMultiple=True, verify=True)
Gets the main genre of a movie.
- Parameters:
title (str) – the movie name.
year (int) – optional argument. If defined, check only on movies released that year.
checkMultiple (bool) – optional argument. If
True
, then do an involved search where each word in thetitle
is individually capitalized. This functionality was developed to make TMDB movie searches more robust. Default isTrue
.verify (bool) – optional argument, whether to verify SSL connections. Default is
False
.
- Returns:
the main movie genre, which can be one of action, animation, comedy, documentary, drama, hindi, horror, horror, science fiction.
- Return type:
- howdy.movie.movie.get_imdbid_from_id(tmdb_id, verify=True)
- howdy.movie.movie.get_movie_info(tmdb_id, verify=True)
Gets movie information for a movie.
- Parameters:
- Returns:
a comprehensive
dict
of summary information for the movie. For example, for Star Wars,{'adult': False, 'backdrop_path': '/4iJfYYoQzZcONB9hNzg0J0wWyPH.jpg', 'belongs_to_collection': {'id': 10, 'name': 'Star Wars Collection', 'poster_path': '/iTQHKziZy9pAAY4hHEDCGPaOvFC.jpg', 'backdrop_path': '/d8duYyyC9J5T825Hg7grmaabfxQ.jpg'}, 'budget': 11000000, 'genres': [{'id': 12, 'name': 'Adventure'}, {'id': 28, 'name': 'Action'}, {'id': 878, 'name': 'Science Fiction'}], 'homepage': 'http://www.starwars.com/films/star-wars-episode-iv-a-new-hope', 'id': 11, 'imdb_id': 'tt0076759', 'original_language': 'en', 'original_title': 'Star Wars', 'overview': 'Princess Leia is captured and held hostage...', 'popularity': 50.48, 'poster_path': '/btTdmkgIvOi0FFip1sPuZI2oQG6.jpg', 'production_companies': [{'id': 1, 'logo_path': '/o86DbpburjxrqAzEDhXZcyE8pDb.png', 'name': 'Lucasfilm', 'origin_country': 'US'}, {'id': 25, 'logo_path': '/qZCc1lty5FzX30aOCVRBLzaVmcp.png', 'name': '20th Century Fox', 'origin_country': 'US'}], 'production_countries': [{'iso_3166_1': 'US', 'name': 'United States of America'}], 'release_date': '1977-05-25', 'revenue': 775398007, 'runtime': 121, 'spoken_languages': [{'iso_639_1': 'en', 'name': 'English'}], 'status': 'Released', 'tagline': 'A long time ago in a galaxy far, far away...', 'title': 'Star Wars', 'video': False, 'vote_average': 8.2, 'vote_count': 12125}
- Return type:
- howdy.movie.movie.get_movie_tmdbids(title, year=None, getAll=False, verify=True)
Gets either a
list
of TMDB movie IDs that match a movie name, or a single best TMDB movie ID.- Parameters:
title (str) – the movie name.
year (int) – optional argument. If defined, check only on movies released that year.
getAll (bool) – optional argument. If
True
, then find all matches. IfFalse
, only return the best match. Default isFalse
.verify (bool) – optional argument, whether to verify SSL connections. Default is
False
.
- Returns:
If
getAll` is ``True
, then return alist
of all TMDB movie IDs that matchtitle
. If it is `False`, then return a single (int
) best TMDB movie ID match totitle
. If there are no matches, returnNone
.- Return type:
- howdy.movie.movie.get_movies_by_actors(actor_name_dict, verify=True)
Finds the movies where a set of actors have acted together.
- Parameters:
actor_name_dict (dict) – the
dict
, of format returned byget_actor_ids_dict
, of the collection of actors.verify (bool) – optional argument, whether to verify SSL connections. Default is
True
.
- Returns:
a
list
of movies in which these actors have acted. For example, here are the three movies that TMDB found in which Steve Martin and Richard Pryor acted together.[{'title': 'The Muppet Movie', 'release_date': datetime.datetime(1979, 6, 22, 0, 0), 'popularity': 7.743, 'vote_average': 7.1, 'overview': 'Kermit the Frog is persuaded by agent...', 'poster_path': 'https://image.tmdb.org/t/p/w500/48Ve7uLDcPJFGaDnmYYdcV3Ve1M.jpg', 'isFound': False, 'tmdb_id': 11176, 'imdb_id': 'tt0079588'}, {'title': 'And the Oscar Goes To...', 'release_date': datetime.datetime(2014, 2, 2, 0, 0), 'popularity': 4.188, 'vote_average': 7.0, 'overview': 'The story of the gold-plated statuette...', 'poster_path': 'https://image.tmdb.org/t/p/w500/kgH49kPNNtel04HPVGQLS63coRF.jpg', 'isFound': False, 'tmdb_id': 253639, 'imdb_id': 'tt3481232'}, {'title': "Cutting Edge Comedians of the '60s & '70s", 'release_date': datetime.datetime(2007, 4, 10, 0, 0), 'popularity': 0.842, 'vote_average': 0.0, 'overview': 'In the late 1950s, a fresh, unconventional style...', 'poster_path': 'https://image.tmdb.org/t/p/w500/iRHXAdDXwcuKGLH6MmvOUBrhotT.jpg', 'isFound': False, 'tmdb_id': 78710, 'imdb_id': 'tt1002564'}]
If no common movies can be found, then returns an empty list.
- Return type:
- howdy.movie.movie.get_movies_by_title(title, verify=True, apiKey=None)
Gets a collection of movies that the TMDB database finds that matches a movie name.
- Parameters:
- Returns:
a
list
of movies that matchtitle
according to TMDB. For example, 128 movies are a “match” for Star Wars, according to TMDB. Here is the top match (all movies have the samedict
format).{'title': 'Star Wars', 'release_date': datetime.datetime(1997, 1, 31, 0, 0), 'popularity': 50.48, 'vote_average': 8.2, 'overview': 'Princess Leia is captured and held hostage...', 'poster_path': 'https://image.tmdb.org/t/p/w500/btTdmkgIvOi0FFip1sPuZI2oQG6.jpg', 'isFound': False, 'tmdb_id': 11, 'imdb_id': 'tt0076759'}
If no matches can be found, then this method returns an empty list.
- Return type:
See also
- howdy.movie.movie.get_tv_ids_by_series_name(series_name, verify=True)
Returns a
list
of TMDB series IDs that match to a given TV show name.
- howdy.movie.movie.get_tv_info_for_season(tv_id, season, verify=True)
Finds TMDB database information for the TV show and a specific season.
- Parameters:
- Returns:
a comprehensive
dict
of TMDB information on the TV show and the given season. Example nicely formatted JSON representation for The Simpsons Season 10 is located intmdb_simpsons_info.json
. Otherwise returnsNone
if TV show cannot be found.- Return type:
- howdy.movie.movie.get_tv_info_for_series(tv_id, verify=True)
Finds TMDB database information for the TV show.
- Parameters:
- Returns:
a comprehensive
dict
of TMDB information on the TV show. Example nicely formatted JSON representation for The Simpsons is located intmdb_simpsons_info.json
. Otherwise returnsNone
if TV show cannot be found.- Return type:
6.3.3. howdy.movie.movie_torrents module
This module implements higher level interfaces to the Jackett torrent searching server, and functionality that allows for the automatic download of episodes missing from the Plex Movie library. It is very similar to the tv.tv_torrents module, except for the following differences.
methods here are called with
movie_torrent_
instead oftv_torrent_
.no method that searches on the Torrentz torrent tracker.
an extra method,
get_movie_torrent
uses the YTS API to retrieve movie torrent files instead of Magnet links.
Here are the six methods that return the movie magnet links found by different torrent services – get_movie_torrent_eztv_io
(EZTV.IO), get_movie_torrent_zooqle
(Zooqle), get_movie_torrent_rarbg
(RARBG), get_movie_torrent_kickass
(KickassTorrents), get_movie_torrent_tpb
(The Pirate Bay), and the unified torrent searcher get_movie_torrent_jackett
(Jackett torrent search) – produce a common two element tuple
output format.
If successful, then the first element is a
list
of elements that match the searched episode. Each element is adict
, ordered by the total number of seeds and leechs. The second element is the string"SUCCESS"
. The common keys in each element are,title
is usually the name of the candidate movie to download.seeders
is the number of seeds for this Magnet link.leechers
is the number of leeches for this Magnet link.link
is the Magnet URI link.
Some methods may have more keys. For example, the top candidate when running
data, status = get_movie_torrent_zooqle( 'Star Trek Beyond' )
(a search on Zooqle for Star Trek Beyond) is,{'title': 'Star Trek Beyond (2016) [720p] (897.141 MB)', 'raw_title': 'Star Trek Beyond (2016) [720p]', 'seeders': 219, 'leechers': 17, 'link': 'magnet:?xt=urn:btih:87e08ea9ed87fd2b54ba66c755cf054889680f17&dn=Star+Trek+Beyond+(2016)+[720p]&tr=udp%3A%2F%2Ftracker.opentrackr.org%3A1337%2Fannounce&tr=udp%3A%2F%2Fopen.demonii.com%3A1337&tr=udp%3A%2F%2Ftracker.pomf.se%3A80%2Fannounce&tr=udp%3A%2F%2Ftorrent.gresille.org%3A80%2Fannounce&tr=udp%3A%2F%2F11.rarbg.com%2Fannounce&tr=udp%3A%2F%2F11.rarbg.com%3A80%2Fannounce&tr=udp%3A%2F%2Fopen.demonii.com%3A1337%2Fannounce&tr=udp%3A%2F%2Ftracker.openbittorrent.com%3A80&tr=http%3A%2F%2Ftracker.ex.ua%3A80%2Fannounce&tr=http%3A%2F%2Ftracker.ex.ua%2Fannounce&tr=http%3A%2F%2Fbt.careland.com.cn%3A6969%2Fannounce&tr=udp%3A%2F%2Fglotorrents.pw%3A6969%2Fannounce', 'torrent_size' : 940720557}
The extra keys here are
torrent_size
(the size of the candidate in bytes), andraw_title
(the name of the candidate to download). Heretitle
is the name of the candidate, and in parentheses is the size of the download in MB or GB.
An extra method, get_movie_torrent
uses the YTS API to retrieve movie torrent files.
As of October 14, 2024, here are three movie torrent finding methods that work and don’t work when searching for Star Trek Beyond. See Table 5.1 for a description of what services or trackers work for downloading TV torrents.
Torrent Service |
Logo |
Search Method |
Does It Work? |
|
|||
|
|||
|
|||
|
|||
|
|||
Jackett torrent search |
|
||
|
- howdy.movie.movie_torrents.get_movie_torrent(name, verify=True)
Returns a
tuple
of candidate movie found using Torrent files using the YTS API torrent service and the string"SUCCESS"
, if successful.- Parameters:
- Returns:
if successful, then returns a two member
tuple
the first member is alist
of Torrent files that match the searched movie, ordered from earliest to latest year of release. The second element is the string"SUCCESS"
. If this is unsuccessful, then returns an errortuple
of the form returned byreturn_error_raw
.- Return type:
- howdy.movie.movie_torrents.get_movie_torrent_eztv_io(name, maxnum=10, verify=True, tmdb_id=None)
Returns a
tuple
of candidate movie Magnet links found using the EZTV.IO torrent service and the string"SUCCESS"
, if successful.- Parameters:
name (str) – the movie on which to search.
maxnum (int) – optional argument, the maximum number of magnet links to return. Default is 10. Must be \(\ge 5\).
verify (bool) – optional argument, whether to verify SSL connections. Default is
True
.tmdb_id (str) – optional argument. The TMDB ID of the movie.
- Returns:
if successful, then returns a two member
tuple
the first member is alist
of elements that match the searched movie, ordered from most seeds and leechers to least. The second element is the string"SUCCESS"
. The keys in each element of the list are,title
is the name of the candidate movie to download, and in parentheses is the size of the download in MB or GB.rawtitle
is only the name of the candidate movie to download.seeders
is the number of seeds for this Magnet link.leechers
is the number of leeches for this Magnet link.link
is the Magnet URI link.torrent_size
is the size of this torrent in MB.
If this is unsuccessful, then returns an error
tuple
of the form returned byreturn_error_raw
.- Return type:
Warning
As of October 14, 2024, cannot get it to work when giving it valid movie searches, such as
"Star Trek Beyond"
. See Table 6.1.
- howdy.movie.movie_torrents.get_movie_torrent_jackett(name, maxnum=10, verify=True, doRaw=False, tmdb_id=None)
Returns a
tuple
of candidate movie Magnet links found using the main Jackett torrent searching service and the string"SUCCESS"
, if successful.- Parameters:
name (str) – the movie string on which to search.
maxnum (int) – optional argumeent, the maximum number of magnet links to return. Default is 10. Must be \(\ge 5\).
verify (bool) – optional argument, whether to verify SSL connections. Default is
True
.doRaw (bool) – optional argument. If
True
, uses the IMDb information to search for the movie. Otherwise, uses the full string inname
to search for the movie.tmdb_id (int) – optional argument. If defined, use this TMDB movie ID to search for magnet links.
- Returns:
if successful, then returns a two member
tuple
the first member is alist
of elements that match the searched movie, ordered from most seeds and leechers to least. The second element is the string"SUCCESS"
. The keys in each element of the list are,title
is the name of the candidate movie to download, and in parentheses the size of the candidate in MB or GB.rawtitle
is only the name of the candidate movie to download.seeders
is the number of seeds for this Magnet link.leechers
is the number of leeches for this Magnet link.link
is the Magnet URI link.torrent_size
is the size of this torrent in GB.
If this is unsuccessful, then returns an error
tuple
of the form returned byreturn_error_raw
.- Return type:
- howdy.movie.movie_torrents.get_movie_torrent_kickass(name, maxnum=10, verify=True)
Returns a
tuple
of candidate movie Magnet links found using the KickAssTorrents torrent service and the string"SUCCESS"
, if successful.- Parameters:
- Returns:
if successful, then returns a two member
tuple
the first member is alist
of elements that match the searched movie, ordered from most seeds and leechers to least. The second element is the string"SUCCESS"
. The keys in each element of the list are,title
is only the name of the candidate movie to download.seeders
is the number of seeds for this Magnet link.leechers
is the number of leeches for this Magnet link.link
is the Magnet URI link.
If this is unsuccessful, then returns an error
tuple
of the form returned byreturn_error_raw
.- Return type:
Warning
As of October 14, 2024, cannot get it to work when giving it valid movie searches, such as
"Star Trek Beyond"
. See Table 6.1.
- howdy.movie.movie_torrents.get_movie_torrent_rarbg(name, maxnum=10, verify=True)
Returns a
tuple
of candidate movie Magnet links found using the RARBG torrent service and the string"SUCCESS"
, if successful.- Parameters:
- Returns:
if successful, then returns a two member
tuple
the first member is alist
of elements that match the searched movie, ordered from most seeds and leechers to least. The second element is the string"SUCCESS"
. The keys in each element of the list are,title
is only the name of the candidate movie to download.seeders
is the number of seeds for this Magnet link.leechers
is the number of leeches for this Magnet link.link
is the Magnet URI link.
If this is unsuccessful, then returns an error
tuple
of the form returned byreturn_error_raw
.- Return type:
Warning
As of October 14, 2024, cannot get it to work when giving it valid movie searches, such as
"Star Trek Beyond"
. See Table 6.1.
- howdy.movie.movie_torrents.get_movie_torrent_tpb(name, maxnum=10, doAny=False, verify=True)
Returns a
tuple
of candidate movie Magnet links found using the The Pirate Bay torrent service and the string"SUCCESS"
, if successful.- Parameters:
name (str) – the movie string on which to search.
maxnum (int) – optional argument, the maximum number of magnet links to return. Default is 100. Must be \(\ge 5\).
doAny (bool) – optional argument. If
True
, then only search through TV shows. Otherwise, search through all media.verify (bool) – optional argument, whether to verify SSL connections. Default is
True
.
- Returns:
if successful, then returns a two member
tuple
the first member is alist
of elements that match the searched movie, ordered from most seeds and leechers to least. The second element is the string"SUCCESS"
. The keys in each element of the list are,title
is only the name of the candidate movie to download.seeders
is the number of seeds for this Magnet link.leechers
is the number of leeches for this Magnet link.link
is the Magnet URI link.torrent_size
is the size of this torrent in bytes.
If this is unsuccessful, then returns an error
tuple
of the form returned byreturn_error_raw
.- Return type:
Warning
As of October 14, 2024, cannot get it to work when giving it valid movie searches, such as
"Star Trek Beyond"
. See Table 6.1.
- howdy.movie.movie_torrents.get_movie_torrent_zooqle(name, maxnum=10, verify=True)
Returns a
tuple
of candidate movie Magnet links found using the Zooqle torrent service and the string"SUCCESS"
, if successful.- Parameters:
- Returns:
if successful, then returns a two member
tuple
the first member is alist
of elements that match the searched movie, ordered from most seeds and leechers to least. The second element is the string"SUCCESS"
. The keys in each element of the list are,title
is the name of the candidate movie to download, and in parentheses is the size of the download in MB or GB.rawtitle
is only the name of the candidate movie to download.seeders
is the number of seeds for this Magnet link.leechers
is the number of leeches for this Magnet link.link
is the Magnet URI link.torrent_size
is the size of this torrent in MB.
If this is unsuccessful, then returns an error
tuple
of the form returned byreturn_error_raw
.- Return type: