5.3. Howdy TV API
This document describes the lower level Howdy TV API, upon which the command line tools and the GUI tool are built. It lives in howdy.tv
.
5.3.1. howdy.tv module
This module implements the lower-level functionalty that does the following:
Provides the SQLAlchemy ORM class on TV shows to exclude from analysis or update on the Plex server. This is the
showstoexclude
table and is in theShowsToExclude
class.Save and retrieve the TVDB API configuration data from the
plexconfig
table.Retrieve and refresh the TVDB API access token.
- class howdy.tv.ShowsToExclude(**kwargs)
This SQLAlchemy ORM class contains the list of shows to exclude from analysis. These shows must exist on the Plex server. Stored into the
showstoexclude
table in the SQLite3 configuration database.
- class howdy.tv.TMDBShowIds(**kwargs)
This SQLAlchemy ORM class contains the show names with the TMDB IDs of the shows. These shows must exist on the Plex server. Storied in the the
tmdbshowids
table in the SQLite3 configuration database.
- howdy.tv.check_tvdb_api(username, apikey, userkey, verify=True)
Checks whether the TVDB API credentials are valid.
- Parameters:
- Returns:
True
if the credentials are valid,False
otherwise.- Return type:
See also
- howdy.tv.get_token(verify=True, data=None)
Returns the TVDB API token that allows access to the TVDB database. If there are errors, then returns
None
.- Parameters:
- Returns:
the TVDB API token, otherwise returns
None
if there are errors.- Return type:
- howdy.tv.get_tvdb_api()
Returns the
dictionary
of TVDB API credentials (see TVDB API configuration), taken from thetvdb
configuration service in theplexconfig
table. The form of the dictionary is,{ 'username' : USERNAME, # the TVDB API user name 'apikey' : APIKEY, # the TVDB API key 'userkey' : USERKEY # THE TVDB API user key }
- Returns:
- Return type:
- Raises:
ValueError – if the TVDB API credentials are not found in the
plexconfig
table.
- howdy.tv.save_tvdb_api(username, apikey, userkey, verify=True)
Saves the information on the TVDB API access into the
tvdb
configuration service in theplexconfig
table. Details of how to set up the configuration is in the TVDB API configuration, which uses howdy_config_gui.- Parameters:
- Returns:
a satus
string
. If successful, returns"SUCCESS"
. If unsuccessful, returns"FAILURE, COULD NOT SAVE TVDB API STUFF"
.- Return type:
See also
5.3.2. howdy.tv.tv module
This module contains the main back-end functionality used by the Plex TVDB GUIs and CLIs. Here are the main features of this module.
Create calendar eye charts of episodes aired by calendar year.
Search TVDB for all episodes aired for a TV show, and determine those episodes that are missing from one’s Plex TV library.
Extracts useful information on episodes and TV shows that are used by Plex TVDB GUIs and CLIs.
Robust functionality that, with the howdy.tv.tv_torrents module, allows for the automatic download of episodes missing from the Plex TV library.
- class howdy.tv.tv.TVSeason(seriesName, seriesId, token, seasno, verify=True, eps=None)
A convenience object that stores season information for a TV show. This provides a higher level object oriented implementation of the lower level pure method implementation of manipulating TV show data.
- Parameters:
seriesName (str) – the series name.
seasno (int) – the season number. If this is a TV special, then this should be
0
.verify (bool) – optional argument, whether to verify SSL connections. Default is
True
.eps (list) – optional argument. The
list
of TV shows returned by the TVDB API, and whose format is described inget_episodes_series
.
- Variables:
seriesName (str) – the series name.
seasno (int) – the season number. If this is a TV special, then the season number is
0
.img (Image) – the
Image
object associated with this season poster, if found. OtherwiseNone
.episodes (dict) –
a
dict
of episode data. Each key is the episode number. Each value is adict
of TVDB summary of that episode.airedEpisodeNumber
is the episode number in the season.airedSeason
is the season.airedDate
is thedate
on which the episode aired.overview
is the summary of the episode.
- class howdy.tv.tv.TVShow(seriesName, seriesInfo, token, verify=True, showSpecials=False)
A convenience object that stores TV show information for a TV show. This provides a higher level object oriented implementation of the lower level pure method implementation of manipulating TV show data.
- Parameters:
seriesName (str) – the series name.
seriesInfo (dict) – the subdictionary of the Plex TV library information returned by
get_library_data
associated withseriesName
. Iftvdata
is the Plex TV library information, thenseriesInfo = tvdata[ seriesName ]
.verify (bool) – optional argument, whether to verify SSL connections. Default is
True
.showSpecials (bool) – optional argument. If
True
, then also collect information on TV specials associated with this TV show. Default isFalse
.
- Variables:
seriesName (str) – the series name,
statusEnded (bool) – whether the series has ended.
imageURL (str) – the URL of the TV series.
isPlexImage (bool) –
True
if the URL came from the Plex server,False
if it came from TVDB.overview (str) – summary of the TV series.
seasonDict (dict) – a
dict
, whose keys are the season numbers and whose values are theTVSeason
associated with that season of the series.startDate (date) – the first
date
aired date for the series.lastDate (date) – the last
date
aired date for the series.
- Raises:
ValueError – if cannot find the TV show with this name, or otherwise cannot construct this object.
- classmethod create_tvshow_dict(tvdata, token=None, verify=True, debug=False, num_threads=24)
Higher level convenience method that returns a
dict
of show names to their correspondingTVShow
object.- Parameters:
tvdata (dict) – the Plex TV library information returned by
get_library_data
.verify (bool) – optional argument, whether to verify SSL connections. Default is
True
.False (debug) – optional argument. If
True
, run withDEBUG
logging
mode. Default isFalse
.num_threads (int) – the number of threads over which to parallelize this calculation. The default is twice the number of cores on the CPU.
- Returns:
a
dict
, whose keys are the TV show names and whose values are theTVShow
associated with that TV show.- Return type:
- get_episode_name(airedSeason, airedEpisode)
- get_episodes_series(showSpecials=True, fromDate=None)
- Parameters:
- Returns:
a
list
oftuples
. Each tuple is of type( SEASON NUMBER, EPISODE NUMBER IN SEASON )
. Specials have a season number of0
.- Type:
- get_tot_epdict_tvdb()
- Returns:
a summary nested
dict
of episode information for a given TV show.
The top level dictionary has keys that are the TV show’s seasons. Each value is a second level dictionary of information about each season.
The second level dictionary has keys (for each season) that are the season’s episodes. Each value is a
tuple
of episode name and air date, as adate
.
An example of the output format is described in the pure method
get_tot_epdict_tvdb
.- Return type:
See also
- howdy.tv.tv.create_plot_year_tvdata(tvdata_date_dict, year=2010, shouldPlot=True, dirname=None, format='svg')
Creates a calendar eye chart of episodes aired during a given calendar year. This either creates an SVG file, or shows the chart on the screen. An example chart is shown in Fig. 5.1.
- Parameters:
tvdata_date_dict (dict) – the
dictionary
of Plex TV library episodes, organized by date aired.year (int) – the calendar year for which to create an eye chart of episodes aired.
shouldPlot (bool) – if
True
, then create an SVG file namedtvdata.YEAR.svg
or a PNG file namedtvdata.YEAR.png
. Otherwise plot this eye chart on the screen.dirname (str) – the directory into which a file should be created (only applicable when
shouldPlot = True
). IfNone
, then defaults to current working directory. If notNone
, then must be a valid directory.format (str) – format of the figure to make (only runs if
shouldPlot
isTrue
). Can be onlysvg
orpng
.
- howdy.tv.tv.create_tvTorUnits(toGet, restrictMaxSize=True, restrictMinSize=True, do_raw=False, must_have={})
Used by, e.g., get_tv_batch, to download missing episodes on the Plex TV library. This returns a
tuple
of alist
of missing episodes to (torrent) download from the remote Deluge torrent server, and alist
of new directories to create, given a set of missing episode information,toGet
, as produced byget_remaining_episodes
.$LIBRARY_DIR
is the TV library’s location on the Plex server.The first element of the tuple is a list of missing episodes to download using the remote Deluge server (see Section 2.2.2 on the server’s setup). Each element in the list consists of summary information, as a dictionary, that describes those TV Magnet links to download. Here are the keys.
totFname
is the destination prefix (without file extension) of the episode on the Plex server.torFname
is the search string to give to the Jackett server (see Section 2.1.5 on the Jackett server’s setup) to search for and download this episode.torFname_disp
is the logging output giving the raw name of the episode (show name, season, epno) used in, e.g., get_tv_batch.minSize
is the minimum size, in MB, of the H264 encoded MP4 or MKV episode file to search for.maxSize
is the maximum size, in MB, of the H264 encoded MP4 or MKV episode file to search for.tvshow
is the name of the TV show to which this missing episode belongs.do_raw
is aboolean
flag. IfTrue
, then search for this missing episode through the Jackett server using available IMDb information. IfFalse
, then do a raw text search ontorFname
to find episode Magnet links.must_have
is aset
of strings over which to filter the search for Magnet links to download. By default it is an emptyset
.
For example, here is a representation of a missing episode that will be fed to the Deluge server for download.
{ 'totFname': '$LIBRARY_DIR/The Great British Bake Off/Season 5/The Great British Bake Off - s05e12 - Masterclass 2', 'torFname': 'The Great British Bake Off S05E12', 'torFname_disp': 'The Great British Bake Off S05E12', 'minSize': 300, 'maxSize': 800, 'tvshow': 'The Great British Bake Off', 'do_raw': False, 'must_have' : {}, }
The second element is a
list
of new directories to create for missing episodes. In this example, there are new episodes for season 10 of The Great British Bake Off, but no season 10 directory.[ '$LIBRARY_DIR/The Great British Bake Off/Season 10' ]
- Parameters:
toGet (dict) – a
dict
of missing episodes by TV show on the Plex server, of the format returned byget_remaining_episodes
.restrictMaxSize (bool) – if
True
, then restrict the maximum size of H264 or H265/HEVC videos to search for on the Jackett server. Default isTrue
.restrictMinSize (bool) – if
True
, then restrict the minimum size of H264 or H265/HEVC videos to search for on the Jackett server. Default isTrue
.do_raw (bool) – if
False
, then search for Magnet links of missing episodes using their IMDb information. IfTrue
, then search using the raw string. Default isFalse
.must_have (set) – the
set
of strings over which to filter the search for Magnet links to download. By default it is an emptyset
.
- Returns:
a
tuple
of two elements. The first element is alist
of missing episodes to search on the Jackett server. The second element is alist
of new directories to create for the TV library.- Return type:
- howdy.tv.tv.did_series_end(series_id, tvdb_token, verify=True, date_now=None)
Check on shows that have ended more than 365 days from the last day.
- Parameters:
verify (bool) – optional argument, whether to verify SSL connections. Default is
True
.date_now (date) – an optional specific last
date
to describe when a show was deemed to have ended. That is, if a show has not aired any episodes more than 365 days beforedate_now
, then define the show as ended. By default,date_now
is the current date.
- Returns:
True
if the show is “ended,” otherwiseFalse
.- Return type:
- Raises:
ValueError – if we get a 200 response, but the response does not contain JSON data.
- howdy.tv.tv.download_batched_tvtorrent_shows(tvTorUnits, newdirs=[], maxtime_in_secs=240, num_iters=10, do_raw=False, do_local_rsync=False)
Engine backend code, used by get_tv_batch, that searches for Magnet links for missing episodes on the Jackett server, downloads the Magnet links using the Deluge server, and finally copies the downloaded missing episodes to the appropriate locations in the Plex TV library. This expects the
tuple
input returned bycreate_tvTorUnits
to run.- Parameters:
tvTorUnits (list) – the
list
of missing episodes to search on the Jackett server. This is the first element of thetuple
returned bycreate_tvTorUnits
.newdirs (list) – the
list
of new directories to create for the TV library. This is the second element of thetuple
returned bycreate_tvTorUnits
.maxtime_in_secs (int) – optional argument, the maximum time to wait for a Magnet link found by the Jackett server to fully download through the Deluge server. Must be \(\ge 60\) seconds. Default is 240 seconds.
num_iters (int) – optional argument, the maximum number of Magnet links to try and fully download before giving up. The list of Magnet links to try for each missing episode is ordered from most seeders + leechers to least. Must be \(\ge 1\). Default is 10.
do_raw (bool) – if
False
, then search for Magnet links of missing episodes using their IMDb information. IfTrue
, then search using the raw string. Default isFalse
.do_local_rsync (bool) – if
False
, then do remote ssh rsync download into local directory. Otherwise do a move from “local” origin directory. Default isFalse
.
- howdy.tv.tv.get_all_series_didend(tvdata, verify=True, num_threads=24, tvdb_token=None)
Returns a
dict
on which TV shows on the Plex server have ended. Each key is the TV show, and its value is whether the show ended or not. Here is its format.{ '11.22.63': True, 'Fargo': False, 'Night Court': True, 'Two and a Half Men': True, '24': True, ... }
- Parameters:
tvdata (dict) – the Plex TV library information returned by
get_library_data
.verify (bool) – optional argument, whether to verify SSL connections. Default is
True
.num_threads (int) – the number of threads over which to parallelize this calculation. The default is twice the number of cores on the CPU.
tvdb_token (str) – optional TVDB API access token. If
None
, then gets the TVDB API access token withget_token
.
- Returns:
the
dict
of TV shows on the Plex server and whether each has ended or not.- Type:
- howdy.tv.tv.get_episode_id(series_id, airedSeason, airedEpisode, tvdb_token, verify=True)
Returns the TVDB
int
episode ID of an episode, given its TVDB series ID, season, and episode number. If cannot be found, then returnsNone
.- Parameters:
- Returns:
- Return type:
- howdy.tv.tv.get_episode_name(series_id, airedSeason, airedEpisode, tvdb_token, verify=True)
Returns the episode given its TVDB series ID, season number, and episode number. If cannot be found, then returns
None
.- Parameters:
- Returns:
the
str
episode name.- Return type:
- howdy.tv.tv.get_episodes_series(series_id, tvdb_token, showSpecials=True, fromDate=None, verify=True, showFuture=False)
Returns a large and comprehensive
list
of TVDB episode info on a given TV show. Example TVDB show data for The Simpsons, represented as a JSON file, is located intvdb_simpsons_info.json
. Each element of the list is an episode, and the list is ordered from earliest aired episode to latest aired episode.- Parameters:
showSpecials (bool) – if
True
, also include episode info for TV specials for that given series. Default isTrue
.fromDate (date) – optional first
date
after which to collect TVDB episode information. If not defined, then include information on all episodes from the first one aired.verify (bool) – optional argument, whether to verify SSL connections. Default is
True
.showFuture (bool) – optional argument, if
True
then also include information on episodes that have not yet aired.
- Returns:
the
list
of unified TVDB information on a TV show. Seetvdb_simpsons_info.json
.- Return type:
- howdy.tv.tv.get_future_info_shows(tvdata, verify=True, showsToExclude=None, token=None, fromDate=None, num_threads=24)
Returns a
dict
on which TV shows on the Plex server have a new season to start. Each key is a TV show in the Plex library. Each value is another dictionary:max_last_season
is the latest season of the TV show,min_next_season
is the next season to be aired, andstart_date
is the firstdate
that a new episode will air.- Parameters:
tvdata (dict) – the Plex TV library information returned by
get_library_data
.verify (bool) – optional argument, whether to verify SSL connections. Default is
True
.showsToExclude (list) – the list of TV shows on the Plex server to ignore. Default is to not ignore any TV show.
token (str) – optional TVDB API access token. If
None
, then gets the TVDB API access token withget_token
.fromDate (date) – optional start
date
after which to search for new episodes. That is, if defined then only look for future episodes aired on or after this date. If not defined, then look for any aired episode to be aired after the current date.num_threads (int) – the number of threads over which to parallelize this calculation. The default is twice the number of cores on the CPU.
- Returns:
a
dict
of TV shows that will start airing new episodes. An example output of this method is shown here,{'American Crime Story': {'max_last_season': 2, 'min_next_season': 3, 'start_date': datetime.date(2020, 9, 27)}, 'BoJack Horseman': {'max_last_season': 5, 'min_next_season': 6, 'start_date': datetime.date(2019, 10, 25)}, 'Homeland': {'max_last_season': 7, 'min_next_season': 8, 'start_date': datetime.date(2020, 2, 9)}, ... }
- Return type:
See also
- howdy.tv.tv.get_imdb_id(series_id, tvdb_token, verify=True)
Returns the IMDb string ID given a TVDB series ID, otherwise return
None
if show’s IMDb ID cannot be found.
- howdy.tv.tv.get_path_data_on_tvshow(tvdata, tvshow)
This method is used by the get_tv_batch tool that can automatically download new episodes. This returns a summary
dict
of information on a TV show stored in the Plex server (see documentation inget_library_data
that focuses on the format of the dictionary for TV libraries). Here is a guide to the keys:prefix
is the root directory in which the episodes of the TV show live.showFilename
is the prefix of all episodes of this TV show. Here for instance, a new Simpsons episode, say S31E06, would start with"The Simpsons - s31e06 - ..."
.season_prefix_dict
is a dictionary of sub-directories, by season, in which the episodes live. For example, season 1 episodes live in"$LIBRARY_DIR/The Simpsons/Season 01"
.min_inferred_length
refers to the padding of season number. Thisinteger
must be \(\ge 1\). Heremin_inferred_length = 2
, so seasons are numbered as"Season 01"
.episode_number_length
is the formatting on each episode number. Two means that episode numbers for this TV show are formatted as01-99
. This becomes important for TV shows in which there are 100 or more episodes in a season, such as The Adventures of Rocky and Bullwinkle and Friends.avg_length_mins
is the average episode length, in minutes.
- Parameters:
tvdata (dict) – the Plex TV library information returned by
get_library_data
.tvshow (str) – the TV show’s name.
- Returns:
the summary
dict
for the TV show on this Plex server’s TV library. For example, here is the summary information on The Simpsons given in thetvdata
, the dictionary representation of TV library data.$LIBRARY_DIR
is the TV library’s location on the Plex server.>> simpsons_summary = get_path_data_on_tvshow( tvdata, 'The Simpsons' ) >> {'prefix': '$LIBRARY_DIR/The Simpsons', 'showFileName': 'The Simpsons', 'season_prefix_dict': {1: 'Season 01', 2: 'Season 02', 3: 'Season 03', 4: 'Season 04', 5: 'Season 05', 6: 'Season 06', 7: 'Season 07', 8: 'Season 08', 9: 'Season 09', 10: 'Season 10', 11: 'Season 11', 12: 'Season 12', 13: 'Season 13', 14: 'Season 14', 15: 'Season 15', 16: 'Season 16', 17: 'Season 17', 18: 'Season 18', 19: 'Season 19', 20: 'Season 20', 21: 'Season 21', 22: 'Season 22', 23: 'Season 23', 24: 'Season 24', 25: 'Season 25', 26: 'Season 26', 27: 'Season 27', 28: 'Season 28', 29: 'Season 29', 30: 'Season 30', 31: 'Season 31'}, 'min_inferred_length': 2, 'episode_number_length': 2, 'avg_length_mins': 22.0}
If
tvshow
is not found, then returnsNone
.- Return type:
- howdy.tv.tv.get_possible_ids(series_name, tvdb_token, verify=True)
Returns a
tuple
of candidate TV shows from the TVDB database that match a series name, and status string. If matches could not be found, returns an errortuple
returned byreturn_error_raw
– first element isNone
, second element isstr
error message.The form of the candidate TV shows is a list of dictionaries. Each dictionary is a candidate TV show: the
'id'
key is theint
TVDB series ID, and the'seriesName'
key is thestr
series name. For example, for The Simpsons>> candidate_series, _ = get_possible_ids( 'The Simpsons', tvdb_token ) >> [{'id': 71663, 'seriesName': 'The Simpsons'}, {'id': 76580, 'seriesName': "Paul Merton in Galton & Simpson's..."}, {'id': 153221, 'seriesName': "Jessica Simpson's The Price of Beauty"}]
- Parameters:
- Returns:
a
tuple
of candidate TVDB series that matchseries_name
, and thestr
'SUCCESS'
. Otherwise an error tuple returned byreturn_error_raw
.- Return type:
- howdy.tv.tv.get_remaining_episodes(tvdata, showSpecials=True, fromDate=None, verify=True, doShowEnded=False, showsToExclude=None, showFuture=False, num_threads=24, token=None, mustHaveTitle=True)
Returns a
dict
of episodes missing from the Plex TV library for the TV shows that are in it. Each key in the dictionary is the TV show with missing episodes. The value is another dictionary. Here are their keys and values,episodes
returns alist
oftuple
s of missing episodes. Each tuple is of the form( SEASON #, EPISODE #, EPISODE NAME )
.the remaining keys –
prefix
,showFilename
,min_inferred_length
,season_prefix_dict
,episode_number_length
,avg_length_mins
– and their values have the same meaning as the summary Plex TV library returned byget_path_data_on_tvshow
.
- Parameters:
tvdata (dict) – the Plex TV library information returned by
get_library_data
.showSpecials (bool) – if
True
, also include episode info for TV specials for that given series. Default isTrue
.fromDate (date) – optional start
date
from which to search for new episodes. That is, if defined then only look for missing episodes aired on or after this date. If not defined, then look for any aired episode missing from this Plex TV library.verify (bool) – optional argument, whether to verify SSL connections. Default is
True
.doShowEnded (bool) – if
True
, then also look for missing episodes from shows that have ended. Default isFalse
.showsToExclude (list) – the list of TV shows on the Plex server to ignore. Default is to not ignore any TV show.
showFuture (bool) – if
True
, then also include missing episodes that have not aired yet. Default isFalse
.num_threads (int) – the number of threads over which to parallelize this calculation. The default is twice the number of cores on the CPU.
token (str) – optional TVDB API access token. If
None
, then gets the TVDB API access token withget_token
.mustHaveTitle (bool) – sometimes new episodes are registered in TVDB but without titles. Functionality to download missing episodes to the Plex server (see, e.g., get_tv_batch) fails if the episode does not have a name. If
True
, then ignore new episodes that do not have titles. Default isTrue
.
- Returns:
a
dict
of missing episodes by TV show on the Plex server. Here is some example output.$LIBRARY_DIR
is the TV library’s location on the Plex server, and The Great British Bake Off is a British reality TV show on baking.{'The Great British Bake Off': {'episodes': [(5, 12, 'Masterclass 2'), (5, 13, 'Class of 2013'), (5, 14, 'Masterclass 3'), (5, 15, 'Masterclass 4'), (7, 11, 'Class of 2015'), (10, 1, 'Cake Week'), (10, 2, 'Biscuit Week'), (10, 3, 'Bread Week'), (10, 4, 'Dairy Week'), (10, 5, 'The Roaring Twenties'), (10, 6, 'Dessert Week'), (10, 7, 'Festival Week'), (10, 8, 'Pastry Week')], 'prefix': '$LIBRARY_DIR/The Great British Bake Off', 'showFileName': 'The Great British Bake Off', 'min_inferred_length': 1, 'season_prefix_dict': {0: 'Specials', 1: 'Season 1', 2: 'Season 2', 3: 'Season 3', 4: 'Season 4', 5: 'Season 5', 6: 'Season 6', 7: 'Season 7', 8: 'Season 8', 9: 'Season 9'}, 'episode_number_length': 2, 'avg_length_mins': 52.0}}
- Return type:
See also
- howdy.tv.tv.get_series_id(series_name, token, verify=True)
Returns the TVDB series ID given its series name. If no candidate is found, returns
None
.
- howdy.tv.tv.get_series_image(series_id, tvdb_token, verify=True)
Returns a
tuple
of the TVDB URL of the TV show’s poster AND the string “SUCCESS”, if found. Otherwise returns an errortuple
given byreturn_error_raw
. :param int series_id: the TVDB database series ID. :param str tvdb_token: the TVDB API access token. :param bool verify: optional argument, whether to verify SSL connections. Default isTrue
.- Returns:
a
tuple
of TV show poster URL, and thestr
'SUCCESS'
. For example, here is the TVDB poster URL for The Simpsons.>> series_id = get_series_id( 'The Simpsons', tvdb_token ) >> series_image, _ = get_series_image( series_id, tvdb_token ) >> 'https://thetvdb.com/banners/posters/71663-1.jpg'
Otherwise an error tuple returned by
return_error_raw
.- Return type:
See also
- howdy.tv.tv.get_series_info(series_id, tvdb_token, verify=True)
Returns a
tuple
of TVDB summary information AND the string “SUCCESS” for a given Tv show, otherwise returns an errortuple
given byreturn_error_raw
.- Parameters:
- Returns:
a
tuple
of candidate TV show info, and thestr
'SUCCESS'
. For example, here is the summary information returned for The Simpsons.>> series_id = get_series_id( 'The Simpsons', tvdb_token ) >> series_info, _ = get_series_info( series_id, tvdb_token ) >> {'id': 71663, 'seriesName': 'The Simpsons', 'aliases': [], 'banner': 'graphical/71663-g13.jpg', 'seriesId': '146', 'status': 'Continuing', 'firstAired': '1989-12-17', 'network': 'FOX', 'networkId': '', 'runtime': '25', 'genre': ['Animation', 'Comedy'], 'overview': 'Set in Springfield, the average American town...', 'lastUpdated': 1571687688, 'airsDayOfWeek': 'Sunday', 'airsTime': '8:00 PM', 'rating': 'TV-PG', 'imdbId': 'tt0096697', 'zap2itId': 'EP00018693', 'added': '', 'addedBy': None, 'siteRating': 8.9, 'siteRatingCount': 847, 'slug': 'the-simpsons'}
Otherwise an error tuple returned by
return_error_raw
.- Return type:
- howdy.tv.tv.get_series_season_image(series_id, airedSeason, tvdb_token, verify=True)
Returns a
tuple
of the TVDB URL of the TV show’s SEASON poster AND the string “SUCCESS”, if found. Otherwise returns an errortuple
given byreturn_error_raw
. :param int series_id: the TVDB database series ID. :param int airedSeason: the season number of the episode. :param str tvdb_token: the TVDB API access token. :param bool verify: optional argument, whether to verify SSL connections. Default isTrue
.- Returns:
a
tuple
of TV show SEASON poster URL, and thestr
'SUCCESS'
. For example, here is the TVDB season poster URL for The Simpsons, season 10.>> series_id = get_series_id( 'The Simpsons', tvdb_token ) >> season_image, _ = get_series_image( series_id, 10, tvdb_token ) >> 'https://thetvdb.com/banners/seasons/146-10.jpg'
Otherwise an error tuple returned by
return_error_raw
.- Return type:
See also
- howdy.tv.tv.get_shows_to_exclude(tvdata=None)
Returns the list of shows in the Plex library that are ignored from analysis or update. This queries the
showstoexclude
table in the SQLite3 configuration database.- Parameters:
tvdata (dict) – Optional Plex TV library information, returned by
get_library_data
, to query. If not defined, then return the list of excluded TV shows found in the relevant table. If defined, returns an intersection of shows found in the table with TV shows in the Plex library.- Returns:
a
list
of TV shows to ignore.- Return type:
See also
- howdy.tv.tv.get_tot_epdict_tvdb(showName, verify=True, showSpecials=False, showFuture=False, token=None)
Returns a summary nested
dict
of episode information for a given TV show.The top level dictionary has keys that are the TV show’s seasons. Each value is a second level dictionary of information about each season.
The second level dictionary has keys (for each season) that are the season’s episodes. Each value is a
tuple
of episode name and air date, as adate
.
- Parameters:
showName (str) – the TV show’s name.
verify (bool) – optional argument, whether to verify SSL connections. Default is
True
.showSpecials (bool) – if
True
, then also include TV specials. These specials will appear in a season0
in this dictionary.showFuture (bool) – optional argument, if
True
then also include information on episodes that have not yet aired.
- Returns:
a
dict
of TV show episodes that the TVDB has found. An example for The Simpsons is shown below,{1 : {1: ('Simpsons Roasting on an Open Fire', datetime.date(1989, 12, 17)), 2: ('Bart the Genius', datetime.date(1990, 1, 14)), 3: ("Homer's Odyssey", datetime.date(1990, 1, 21)), 4: ("There's No Disgrace Like Home", datetime.date(1990, 1, 28)), 5: ('Bart the General', datetime.date(1990, 2, 4)), 6: ('Moaning Lisa', datetime.date(1990, 2, 11)), 7: ('The Call of the Simpsons', datetime.date(1990, 2, 18)), 8: ('The Telltale Head', datetime.date(1990, 2, 25)), 9: ('Life on the Fast Lane', datetime.date(1990, 3, 18)), 10: ("Homer's Night Out", datetime.date(1990, 3, 25)), 11: ('The Crepes of Wrath', datetime.date(1990, 4, 15)), 12: ('Krusty Gets Busted', datetime.date(1990, 4, 29)), 13: ('Some Enchanted Evening', datetime.date(1990, 5, 13))}, 2: {1: ('Bart Gets an F', datetime.date(1990, 10, 11)), 2: ('Simpson and Delilah', datetime.date(1990, 10, 18)), 3: ('Treehouse of Horror', datetime.date(1990, 10, 24)), 4: ('Two Cars in Every Garage and Three Eyes on Every Fish', datetime.date(1990, 11, 1)), 5: ("Dancin' Homer", datetime.date(1990, 11, 8)), 6: ('Dead Putting Society', datetime.date(1990, 11, 15)), 7: ('Bart vs. Thanksgiving', datetime.date(1990, 11, 22)), 8: ('Bart the Daredevil', datetime.date(1990, 12, 6)), 9: ('Itchy & Scratchy & Marge', datetime.date(1990, 12, 20)), 10: ('Bart Gets Hit by a Car', datetime.date(1991, 1, 10)), 11: ('One Fish, Two Fish, Blowfish, Blue Fish', datetime.date(1991, 1, 24)), 12: ('The Way We Was', datetime.date(1991, 1, 31)), 13: ('Homer vs. Lisa and the Eighth Commandment', datetime.date(1991, 2, 7)), 14: ('Principal Charming', datetime.date(1991, 2, 14)), 15: ('Oh Brother, Where Art Thou?', datetime.date(1991, 2, 21)), 16: ("Bart's Dog Gets an F", datetime.date(1991, 3, 7)), 17: ('Old Money', datetime.date(1991, 3, 28)), 18: ('Brush With Greatness', datetime.date(1991, 4, 11)), 19: ("Lisa's Substitute", datetime.date(1991, 4, 25)), 20: ('The War of the Simpsons', datetime.date(1991, 5, 2)), 21: ('Three Men and a Comic Book', datetime.date(1991, 5, 9)), 22: ('Blood Feud', datetime.date(1991, 8, 11))}, ... }
- Return type:
- howdy.tv.tv.get_tvdata_ordered_by_date(tvdata)
This flattens the TV data, stored as a nested
dict
(see documentation inget_library_data
that focuses on the format of the dictionary for TV libraries) into a dictionary whose keys are thedate
at which episodes have been aired, and whose values are thelist
of episodes aired on that date. Each element of that list is atuple
representing a given episode:( SHOW, SEASON #, EPISODE #, EPISODE TITLE )
.For example, let
tvdata
represent the Plex TV library information collected withget_library_data
. Then here are the episodes on the Plex server aired on the last date.>> tvdata_flatten = get_tvdata_ordered_by_date( tvdata ) >> last_date = max( tvdata_flatten ) >> datetime.date(2019, 10, 21) >> tvdata_flatten[ last_date ] >> [('Robot Chicken', 10, 7, 'Snoopy Camino Lindo in: Quick and Dirty Squirrel Shot'), ('Robot Chicken', 10, 8, "Molly Lucero in: Your Friend's Boob"), ('The Deuce', 3, 7, "That's a Wrap"), ('Travel Man: 48 Hours in...', 10, 1, 'Dubrovnik')]
- Parameters:
tvdata (dict) – the Plex TV library information returned by
get_library_data
.- Returns:
a
dict
of episodes. Each key is the date a list of episodes aired. The value is the list of episodes.- Return type:
See also
- howdy.tv.tv.push_shows_to_exclude(tvdata, showsToExclude)
Adds a list of new shows to exclude from analysis or update in the Plex TV library. This updates the
showstoexclude
table in the SQLite3 configuration database with new shows. The shows in the list must exist in the Plex server.- Parameters:
tvdata (dict) – the Plex TV library information returned by
get_library_data
.showsToExclude (list) – the list of TV shows on the Plex server to ignore. Default is to not ignore any TV show.
See also
5.3.3. howdy.tv.tv_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 TV library.
The seven methods that return the episode magnet links found by different torrent services – get_tv_torrent_eztv_io
(EZTV.IO), get_tv_torrent_zooqle
(Zooqle), get_tv_torrent_rarbg
(RARBG), get_tv_torrent_torrentz
(Torrentz), get_tv_torrent_kickass
(KickassTorrents), get_tv_torrent_tpb
(The Pirate Bay), and the unified torrent searcher get_tv_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 the name of the candidate episode 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_tv_torrent_zooqle( 'The Simpsons S31E01' )
is,{'title': 'The Simpsons S31E01 WEB x264-TBS[ettv]', 'seeders': 182, 'leechers': 68, 'link': 'magnet:?xt=urn:btih:9dd4eac1873901420451fb569feb33ac0da649b5&dn=The+Simpsons+S31E01+WEB+x264-TBS[ettv]&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': 170515743}
The extra key is
torrent_size
, the size of the candidate in bytes.If unsuccesful, then returns an error
tuple
of the form returned byreturn_error_raw
.
As of October 14, 2024, here are the magnet link methods that work and don’t work when searching for "The Simpsons S31E01"
.
Torrent Service |
Logo |
Search Method |
Does It Work? |
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
Jackett torrent search |
|
- howdy.tv.tv_torrents.get_tv_torrent_eztv_io(name, maxnum=10, verify=True, series_name=None, minsizes=None, maxsizes=None)
Returns a
tuple
of candidate episode Magnet links found using the EZTV.IO torrent service and the string"SUCCESS"
, if successful.- Parameters:
name (str) – the episode string 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
.series_name (str) – optional argument, the TV show for this episode.
minsizes (list) –
optional
list
ortuple
of size at least 2. Here is its meaning if it is notNone
:maxsizes (list) –
optional
list
ortuple
of size at least 2. Here is its meaning if it is notNone
:
- Returns:
if successful, then returns a two member
tuple
the first member is alist
of elements that match the searched episode, 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 episode to download.rawtitle
is also the name of the candidate episode 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.pubdate
is thedate
at which the magnet link was publshed and put online.
If this is unsuccessful, then returns an error
tuple
of the form returned byreturn_error_raw
.- Return type:
- howdy.tv.tv_torrents.get_tv_torrent_jackett(name, maxnum=10, minSize=0, maxSize=inf, keywords=[], keywords_exc=[], must_have=[], verify=True, series_name=None, raw=False, debug_mode=False)
Returns a
tuple
of candidate episode Magnet links found using the main Jackett torrent searching service and the string"SUCCESS"
, if successful.- Parameters:
name (str) – the episode string on which to search.
maxnum (int) – optional argument, the maximum number of magnet links to return. Default is 10. Must be \(\ge 5\).
minSize (int) – minimum size of the candidate file, in MiB. Default is 0.
maxsize (int) – minimum size of the candidate file, in MiB. Default is infinity.
keywords (list) – optional argument. If not empty, the title of the candidate element must have at least one of the keywords in
keywords
.kewods_exc (list) – optional argument. If not empty, then reject candidate element if title has any keyword in
keywords_exc
.must_have (list) – optional argument. If not empty, then title of the candidate element must have all the keywords in
must_have
.verify (bool) – optional argument, whether to verify SSL connections. Default is
True
.series_name (str) – optional argument. the TV show for this episode.
raw (bool) – if
True
, uses the IMDb information to search for the episode. Otherwise, uses the full string inname
to search for the episode.debug_mode (bool) – if
True
, then dumps out information on the elements that it has found into a (hopefully useful) file name. Default isFalse
.
- Returns:
if successful, then returns a two member
tuple
the first member is alist
of elements that match the searched episode, 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 episode to download, and in parentheses the size of the candidate in MB or GB.rawtitle
also the name of the candidate episode 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 MiB.
If this is unsuccessful, then returns an error
tuple
of the form returned byreturn_error_raw
.- Return type:
- howdy.tv.tv_torrents.get_tv_torrent_kickass(name, maxnum=10, verify=True)
Returns a
tuple
of candidate episode 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 episode, 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 episode 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, I cannot get it to work when giving it valid episode searches, such as
"The Simpsons S31E01"
. See Table 5.1.
- howdy.tv.tv_torrents.get_tv_torrent_rarbg(name, maxnum=10, verify=True)
Returns a
tuple
of candidate episode 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 episode, 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 episode 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, I cannot get it to work when giving it valid episode searches, such as
"The Simpsons S31E01"
. See Table 5.1.
- howdy.tv.tv_torrents.get_tv_torrent_torrentz(name, maxnum=10, verify=True)
Returns a
tuple
of candidate episode Magnet links found using the Torrentz 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 episode, 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 episode 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, I cannot get it to work when giving it valid episode searches, such as
"The Simpsons S31E01"
. See Table 5.1.
- howdy.tv.tv_torrents.get_tv_torrent_tpb(name, maxnum=10, doAny=False, verify=True)
Returns a
tuple
of candidate episode Magnet links found using the The Pirate Bay torrent service and the string"SUCCESS"
, if successful.- Parameters:
name (str) – the episode 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 episode, 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 episode 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, I cannot get it to work when giving it valid episode searches, such as
"The Simpsons S31E01"
. See Table 5.1.
- howdy.tv.tv_torrents.get_tv_torrent_zooqle(name, maxnum=100, verify=True)
Returns a
tuple
of candidate episode 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 episode, 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 episode 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:
- howdy.tv.tv_torrents.return_error_couldnotfind(name)
Returns a
tuple
error message in the format ofreturn_error_raw
, but with the message"Failure, could not find any tv shows with search term <name>"
, where<name>
is the episode torrent that could not be found.- Parameters:
name (str) – the episode torrent to be searched.
- Returns:
a
tuple
of formatreturn_error_raw
, with the error message,"Failure, could not find any tv shows with search term <name>"
.- Return type:
See also
- howdy.tv.tv_torrents.worker_process_download_tvtorrent(tvTorUnit, client=None, maxtime_in_secs=14400, num_iters=1, kill_if_fail=False)
Used by, e.g., get_tv_batch, to download missing episodes on the Plex TV library. Attempts to use the Deluge server, specified in Section 2.2.2, to download an episode. If successful then uploads the finished episode from the remote SSH server to the Plex server and local directory, specified in Section 2.2.3.
- Parameters:
tvTorUnit (dict) – a
dict
representing a summarized magnet link searching operation on an episode. The format and meaning of this data structure is described increate_tvTorUnits
.client (DelugeRPC) – optional argument, the DelugeRPCClient object that at a low level uses the Deluge server to download the Magnet link at the remote SSH server. If
None
, then this client is created usingget_deluge_client
.maxtime_in_secs (int) – optional argument, the maximum time to wait for a Magnet link found by the Jackett server to fully download through the Deluge server. Must be \(\ge 60\) seconds. Default is 14400 seconds.
num_iters (int) – optional argument, the maximum number of Magnet links to try and fully download before giving up. The list of Magnet links to try for each missing episode is ordered from most seeders + leechers to least. Must be \(\ge 1\). Default is 1.
kill_if_fail (bool) – optional argument. If
True
, then on failing operation kill the torrent download on the Deluge server and delete any files associated with it. IfFalse
, then keep the torrent download on failure.
- Returns:
If successful, creates a two element
tuple
: the first element is the base name of the episode that is uploaded to the Plex server, and the second element is a statusdictionary
with three keys.the
status
is"SUCCESS"
.the
message
describes the final status of the operation.the
time
tells how long, in seconds, the successful operation took.
If unsuccessful, returns a failing tuple: the first element is
None
, and the the second element is a statusdictionary
with three keys.the
status
is"FAILURE"
.the
message
describes the illuminating reason as to how this operation failed.the
time
tells how long, in seconds, the failing operation took.
- Return type:
5.3.4. howdy.tv.tv_attic module
This contains broken, stale, and long-untested and unused Plex TVDB functionality. Some methods may live here until they are actively used in Howdy TV GUIs and CLIs.
- howdy.tv.tv_attic.did_series_end_tmdb(series_id, date_now=None)
Check on shows that have ended more than 365 days from the last day.
- Parameters:
date_now (date) – an optional specific last
date
to describe when a show was deemed to have ended. That is, if a show has not aired any episodes more than 365 days beforedate_now
, then define the show as ended. By default,date_now
is the current date.
- Returns:
True
if the show is “ended,” otherwiseFalse
.- Return type:
- Raises:
ValueError – if we get a 200 response, but the response does not contain JSON data.
- howdy.tv.tv_attic.fix_missing_unnamed_episodes(seriesName, eps, verify=True, showFuture=False)
This supposedly uses the TMDB API to find names for episodes that the TVDB API cannot find.
Deprecated since version 1.0: I have not understood the purpose behind this method in years. No other methods call this it. I might remove this method altogether.
- howdy.tv.tv_attic.fix_show_tmdbid(show, firstAiredYear)
This fixes the database of TV shows with TMDB ids when wrong. DOCUMENTATION TO FOLLOW.
- howdy.tv.tv_attic.get_episodes_series_omdb(imdbID, apikey, fromDate=None)
Returns a
list
of episodes found using the OMDB API. Each element has the following keys,Title
is the episode name.Released
is thestr
representation of the date it was aired.Episode
is the episode number in the season.airedSeason
is the season in which the episode was aired.imdbID
is the IMDB episode ID.imdbRating
is the episode rating (out of 10.0) on IMDB.
For example, for The Simpsons,
[{'Title': 'The Call of the Simpsons', 'Released': '1990-02-18', 'Episode': 7, 'imdbRating': '7.9', 'imdbID': 'tt0701228', 'airedSeason': 1}, {'Title': 'The Telltale Head', 'Released': '1990-02-25', 'Episode': 8, 'imdbRating': '7.7', 'imdbID': 'tt0756398', 'airedSeason': 1}, {'Title': 'Life on the Fast Lane', 'Released': '1990-03-18', 'Episode': 9, 'imdbRating': '7.5', 'imdbID': 'tt0701152', 'airedSeason': 1}, ... ]
- howdy.tv.tv_attic.get_episodes_series_tmdb(tmdbID, fromDate=None, showSpecials=False, showFuture=False)
Returns a
list
of episodes returned by the TMDB API. Each element is a dictionary:name
is the episode name,airedDate
is thedate
the episode aired,season
is the season it aired, andepisode
is the episode number in that season.- Parameters:
fromDate (date) – optional argument, of type
date
. If given, then only return episodes aired after this date.showSpecials (bool) – if
True
, then also include TV specials. These specials will appear in a season0
in this dictionary.showFuture (bool) – optional argument, if
True
then also include information on episodes that have not yet aired.
- Returns:
a
list
of episoes returned by the TMDB database. For example, for The Simpsons,>> series_id = get_series_tmdb_id( 'The Simpsons' ) >> episodes_tmdb = get_episodes_series_tmdb( series_id ) >> [{'episodeName': 'Simpsons Roasting on an Open Fire', 'airedDate': datetime.date(1989, 12, 17), 'airedSeason': 1, 'airedEpisodeNumber': 1}, {'episodeName': 'Bart the Genius', 'airedDate': datetime.date(1990, 1, 14), 'airedSeason': 1, 'airedEpisodeNumber': 2}, {'episodeName': "Homer's Odyssey", 'airedDate': datetime.date(1990, 1, 21), 'airedSeason': 1, 'airedEpisodeNumber': 3}, ... ]
- Return type:
- howdy.tv.tv_attic.get_possible_omdb_ids(series_name, apikey)
Returns a
list
of basic information on TV shows from the OMDB API search of a TV show. Each element in the list is atuple
: the first element is the IMDB series ID, and the second element is alist
of years during which the TV series has aired.- Parameters:
- Returns:
a
list
of IMDB based information on TV shows that match the series name. For example, for The Simpsons.>> get_possible_omdb_ids( 'The Simpsons', omdb_apikey ) >> [ ( 'tt0096697', [ 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 ] ) ]
If unsuccessful, returns
None
.- Return type:
- howdy.tv.tv_attic.get_possible_tmdb_ids(series_name, firstAiredYear=None, minmatch=10.0)
Returns a
list
of candidate TMDB TV shows given the series name. Each element in the list is a dictionary: theid
is the TMDB series ID, andairedYear
is the year in which the first episode aired.- Parameters:
- Returns:
a
list
of candidate TMDB TV shows, otherwiseNone
. For example, for The Simpsons,[{'id': 456, 'name': 'The Simpsons', 'airedYear': 1989}, {'id': 73980, 'name': 'Da Suisa', 'airedYear': 2013}]
- Return type:
- howdy.tv.tv_attic.get_series_omdb_id(series_name, apikey)
Returns the most likely IMDB key, using the OMDB API, for a TV show.
- howdy.tv.tv_attic.get_series_tmdb_id(series_name, firstAiredYear=None, minmatch=50.0)
Returns the first TMDB series ID for a TV show. Otherwise returns
None
if no TV series could be found.
- howdy.tv.tv_attic.get_series_updated_fromdate(date, token, verify=True)
a
set
of TVDB series IDs of TV shows that have been updated at least four weeks fron now.
- howdy.tv.tv_attic.get_tot_epdict_imdb(showName, firstAiredYear=None)
Returns a summary nested
dict
of episode information for a given TV show, usingCinemagoer
class in the Cinemagoer Python Package.The top level dictionary has keys that are the TV show’s seasons. Each value is a second level dictionary of information about each season.
The second level dictionary has keys (for each season) that are the season’s episodes. Each value is a
tuple
of episode name and air date, as adate
.
An example of the structure of this dictionary can be found in
get_tot_epdict_tvdb
.
- howdy.tv.tv_attic.get_tot_epdict_omdb(showName, apikey, inYear=None)
- Parameters:
- Returns:
a
dict
of episode information for that TV show. For example, for The Simpsons (here the collection of episodes is incomplete),{ 1: {7: 'The Call of the Simpsons', 8: 'The Telltale Head', 9: 'Life on the Fast Lane', 10: "Homer's Night Out", 11: 'The Crepes of Wrath', 12: 'Krusty Gets Busted', 13: 'Some Enchanted Evening'}, 2: {1: 'Bart Gets an F', 2: 'Simpson and Delilah', 3: 'Treehouse of Horror', 4: 'Two Cars in Every Garage and Three Eyes on Every Fish', 6: 'Dead Putting Society', 12: 'The Way We Was', 13: 'Homer vs. Lisa and the 8th Commandment', 14: 'Principal Charming', 15: 'Oh Brother, Where Art Thou?', 16: "Bart's Dog Gets an F", 17: 'Old Money', 18: 'Brush with Greatness', 19: "Lisa's Substitute", 20: 'The War of the Simpsons', 21: 'Three Men and a Comic Book', 22: 'Blood Feud'}, ... }
If unsuccessful, then returns
None
.- Return type:
See also
- howdy.tv.tv_attic.get_tot_epdict_singlewikipage(epURL, seasnums=1, verify=True)
Returns a dictionary of episodes from a Wikipedia URL for a TV show.
- Parameters:
- Returns:
a
dict
of episodes for this season. Each key is the episode number, and each value is the episode name.- Return type:
Deprecated since version 1.0: This may not reliably work at all anymore! This is very brittle and has not been used since 2015.
- howdy.tv.tv_attic.get_tot_epdict_tmdb(showName, firstAiredYear=None, showSpecials=False, showFuture=False, minmatch=50.0)
Returns a
dict
of episodes found from the TMDB API. The top level dictionary’s keys are the season numbers, and each value is the next-level dictionary of season information. The next level, season dictionary’s keys are the episode number, and its values are a two-element :tuple: of episode names and aired dates (as adate
object). This two level dictionary has the same format as the output fromget_tot_epdict_tvdb
.- Parameters:
showName (str) – the series name.
firstAiredYear (int) – optional argument. If provided, filter on TV shows that were first aired that year.
showSpecials (bool) – if
True
, then also include TV specials. These specials will appear in a season0
in this dictionary.showFuture (bool) – optional argument, if
True
then also include information on episodes that have not yet aired.minmatch (float) – the minimal matching of the series name. Default is 50.0.
- Returns:
a
dict
of episode information for that TV show. For example, for The Simpsons,{1: {1: ('Simpsons Roasting on an Open Fire', datetime.date(1989, 12, 17)), 2: ('Bart the Genius', datetime.date(1990, 1, 14)), 3: ("Homer's Odyssey", datetime.date(1990, 1, 21)), 4: ("There's No Disgrace Like Home", datetime.date(1990, 1, 28)), 5: ('Bart the General', datetime.date(1990, 2, 4)), 6: ('Moaning Lisa', datetime.date(1990, 2, 11)), 7: ('The Call of the Simpsons', datetime.date(1990, 2, 18)), 8: ('The Telltale Head', datetime.date(1990, 2, 25)), 9: ('Life on the Fast Lane', datetime.date(1990, 3, 18)), 10: ("Homer's Night Out", datetime.date(1990, 3, 25)), 11: ('The Crepes of Wrath', datetime.date(1990, 4, 15)), 12: ('Krusty Gets Busted', datetime.date(1990, 4, 29)), 13: ('Some Enchanted Evening', datetime.date(1990, 5, 13))}, ... }
If unsuccessful, then returns
None
.- Return type: