5.3. Howdy TV API 

howdy.tv.get_tvdb_api()

Returns the dictionary of TVDB API credentials (see TVDB API configuration), taken from the tvdb configuration service in the plexconfig 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:: the dict of TVDB API credentials.
Return type:: dict
Raises:: ValueError – if the TVDB API credentials are not found in the plexconfig table.

howdy.tv.refresh_token(token, verify=True)

Refreshes the TVDB API token.

Parameters:

token (str) – a previous valid TVDB API access token.
verify (bool) – optional argument, whether to verify SSL connections. Default is True.

Returns:

a new TVDB API string token. If there are others, returns None.

Return type:

howdy.tv.save_tvdb_api(username, apikey, userkey, verify=True)

Saves the information on the TVDB API access into the tvdb configuration service in the plexconfig table. Details of how to set up the configuration is in the TVDB API configuration, which uses howdy_config_gui.

Parameters:

username (str) – the TVDB API username.
apikey (str) – the TVDB API key.
userkey (str) – the TVDB API user key.
verify (bool) – optional argument, whether to verify SSL connections. Default is True.

Returns:

a satus string. If successful, returns "SUCCESS". If unsuccessful, returns "FAILURE, COULD NOT SAVE TVDB API STUFF".

Return type:

See also

check_tvdb_api.

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.
seriesId (int) – the TVDB series ID.
token (str) – the TVDB API access token.
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 in get_episodes_series.

Variables:

seriesName (str) – the series name.
seriesId (int) – the TVDB series ID.
seasno (int) – the season number. If this is a TV special, then the season number is 0.
imageURL (str) – the TVDB URL of the season poster.
img (Image) – the Image object associated with this season poster, if found. Otherwise None.
episodes (dict) –
a dict of episode data. Each key is the episode number. Each value is a dict of TVDB summary of that episode.
- airedEpisodeNumber is the episode number in the season.
- airedSeason is the season.
- airedDate is the date on which the episode aired.
- overview is the summary of the episode.

get_max_date()

Returns:: the last date of episodes aired this season.
Return type:: date

get_min_date()

Returns:: the first date of episodes aired this season.
Return type:: date

get_num_episodes()

Returns:: the total number of episodes for this season.
Return type:: int

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 with seriesName. If tvdata is the Plex TV library information, then seriesInfo = tvdata[ seriesName ].
token (str) – the TVDB API access token.
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 is False.

Variables:

seriesId (int) – the TVDB series ID.
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 the TVSeason 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=16)

Higher level convenience method that returns a dict of show names to their corresponding TVShow object.

Parameters:

tvdata (dict) – the Plex TV library information returned by get_library_data.
token (str) – optional argument. The TVDB API access token.
verify (bool) – optional argument, whether to verify SSL connections. Default is True.
False (debug) – optional argument. If True, run with DEBUG logging mode. Default is False.
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 the TVShow associated with that TV show.

Return type:

get_episode_name(airedSeason, airedEpisode)

Parameters:

airedSeason (int) – the season number.
airedEpisode (int) – episode number.

Returns:

a tuple, of episode name and aired date (of type date), associated with that episode.

Return type:

Raises:

ValueError – if cannot find the episode aired at the season and episode number.

get_episodes_series(showSpecials=True, fromDate=None)

Parameters:

showSpecials (bool) – optional argument. If True then include the TV specials. Default is True.
fromDate (date) – optional argument of type date. If provided, only include the episodes aired on or after this date.

Returns:

a list of tuples. Each tuple is of type ( SEASON NUMBER, EPISODE NUMBER IN SEASON ). Specials have a season number of 0.

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 a date.

An example of the output format is described in the pure method get_tot_epdict_tvdb.

Return type:: dict

See also

get_tot_epdict_tvdb.

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 named tvdata.YEAR.svg or a PNG file named tvdata.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). If None, then defaults to current working directory. If not None, then must be a valid directory.
format (str) – format of the figure to make (only runs if shouldPlot is True). Can be only svg or png.

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 a list of missing episodes to (torrent) download from the remote Deluge torrent server, and a list of new directories to create, given a set of missing episode information, toGet, as produced by get_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 a boolean flag. If True, then search for this missing episode through the Jackett server using available IMDb information. If False, then do a raw text search on torFname to find episode Magnet links.
- must_have is a set of strings over which to filter the search for Magnet links to download. By default it is an empty set.
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 by get_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 is True.
restrictMinSize (bool) – if True, then restrict the minimum size of H264 or H265/HEVC videos to search for on the Jackett server. Default is True.
do_raw (bool) – if False, then search for Magnet links of missing episodes using their IMDb information. If True, then search using the raw string. Default is False.
must_have (set) – the set of strings over which to filter the search for Magnet links to download. By default it is an empty set.

Returns:

a tuple of two elements. The first element is a list of missing episodes to search on the Jackett server. The second element is a list of new directories to create for the TV library.

Return type:

See also

get_tv_batch.
get_remaining_episodes.
download_batched_tvtorrent_shows.
worker_process_download_tvtorrent.

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:

series_id (int) – the TVDB database series ID.
tvdb_token (str) – the TVDB API access token.
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 before date_now, then define the show as ended. By default, date_now is the current date.

Returns:

True if the show is “ended,” otherwise False.

Return type:

bool

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 by create_tvTorUnits to run.

Parameters:

tvTorUnits (list) – the list of missing episodes to search on the Jackett server. This is the first element of the tuple returned by create_tvTorUnits.
newdirs (list) – the list of new directories to create for the TV library. This is the second element of the tuple returned by create_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. If True, then search using the raw string. Default is False.
do_local_rsync (bool) – if False, then do remote ssh rsync download into local directory. Otherwise do a move from “local” origin directory. Default is False.

See also

get_tv_batch.
get_remaining_episodes.
create_tvTorUnits.
worker_process_download_tvtorrent.

howdy.tv.tv.get_all_series_didend(tvdata, verify=True, num_threads=16, 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 with get_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 returns None.

Parameters:

series_id (int) – the TVDB database series ID.
airedSeason (int) – the season number of the episode.
airedEpisode (int) – the aired episode number, in the season.
tvdb_token (str) – the TVDB API access token.
verify (bool) – optional argument, whether to verify SSL connections. Default is True.

Returns:

the int TVDB episode ID if found, otherwise None.

Return type:

int

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:

series_id (int) – the TVDB database series ID.
airedSeason (int) – the season number of the episode.
airedEpisode (int) – the aired episode number, in the season.
tvdb_token (str) – the TVDB API access token.
verify (bool) – optional argument, whether to verify SSL connections. Default is True.

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 in tvdb_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:

series_id (int) – the TVDB database series ID.
tvdb_token (str) – the TVDB API access token.
showSpecials (bool) – if True, also include episode info for TV specials for that given series. Default is True.
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. See tvdb_simpsons_info.json.

Return type:

howdy.tv.tv.get_future_info_shows(tvdata, verify=True, showsToExclude=None, token=None, fromDate=None, num_threads=16)

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, and start_date is the first date 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 with get_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_futureshows.

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.

Parameters:

series_id (int) – the TVDB database series ID.
tvdb_token (str) – the TVDB API access token.
verify (bool) – optional argument, whether to verify SSL connections. Default is True.

Returns:

the str IMDb ID of the TV show if found, otherwise None.

Return type:

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 in get_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. This integer must be $\ge 1$. Here min_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 as 01-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 the tvdata, 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',
'Season 02',
'Season 03',
'Season 04',
'Season 05',
'Season 06',
'Season 07',
'Season 08',
'Season 09',
'Season 10',
'Season 11',
'Season 12',
'Season 13',
'Season 14',
'Season 15',
'Season 16',
'Season 17',
'Season 18',
'Season 19',
'Season 20',
'Season 21',
'Season 22',
'Season 23',
'Season 24',
'Season 25',
'Season 26',
'Season 27',
'Season 28',
'Season 29',
'Season 30',
'Season 31'},
    'min_inferred_length': 2,
    'episode_number_length': 2,
    'avg_length_mins': 22.0}

If tvshow is not found, then returns None.

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 error tuple returned by return_error_raw – first element is None, second element is str 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 the int TVDB series ID, and the 'seriesName' key is the str 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:

series_name (str) – the series over which to search on the TVDB database.
tvdb_token (str) – the TVDB API access token.
verify (bool) – optional argument, whether to verify SSL connections. Default is True.

Returns:

a tuple of candidate TVDB series that match series_name, and the str 'SUCCESS'. Otherwise an error tuple returned by return_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=16, 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 a list of tuples 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 by get_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 is True.
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 is False.
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 is False.
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 with get_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 is True.

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

get_path_data_on_tvshow.
get_tv_batch.

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.

Parameters:

series_name (str) – the series name for which to search.
token (str) – the TVDB API access token.
verify (bool) – optional argument, whether to verify SSL connections. Default is True.

Returns:

the int TVDB series ID for a series if found, otherwise None.

Return type:

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 error tuple given by return_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 is True.

Returns:

a tuple of TV show poster URL, and the str '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:

get_series_season_image.

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 error tuple given by return_error_raw.

Parameters:

series_id (int) – the TVDB database series ID.
tvdb_token (str) – the TVDB API access token.
verify (bool) – optional argument, whether to verify SSL connections. Default is True.

Returns:

a tuple of candidate TV show info, and the str '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 error tuple given by return_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 is True.

Returns:

a tuple of TV show SEASON poster URL, and the str '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

get_series_image.

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:: list

See also

push_shows_to_exclude.

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 a date.

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 season 0 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)),
('Bart the Genius', datetime.date(1990, 1, 14)),
("Homer's Odyssey", datetime.date(1990, 1, 21)),
("There's No Disgrace Like Home", datetime.date(1990, 1, 28)),
('Bart the General', datetime.date(1990, 2, 4)),
('Moaning Lisa', datetime.date(1990, 2, 11)),
('The Call of the Simpsons', datetime.date(1990, 2, 18)),
('The Telltale Head', datetime.date(1990, 2, 25)),
('Life on the Fast Lane', datetime.date(1990, 3, 18)),
("Homer's Night Out", datetime.date(1990, 3, 25)),
('The Crepes of Wrath', datetime.date(1990, 4, 15)),
('Krusty Gets Busted', datetime.date(1990, 4, 29)),
('Some Enchanted Evening', datetime.date(1990, 5, 13))},
{1: ('Bart Gets an F', datetime.date(1990, 10, 11)),
('Simpson and Delilah', datetime.date(1990, 10, 18)),
('Treehouse of Horror', datetime.date(1990, 10, 24)),
('Two Cars in Every Garage and Three Eyes on Every Fish',
      datetime.date(1990, 11, 1)),
("Dancin' Homer", datetime.date(1990, 11, 8)),
('Dead Putting Society', datetime.date(1990, 11, 15)),
('Bart vs. Thanksgiving', datetime.date(1990, 11, 22)),
('Bart the Daredevil', datetime.date(1990, 12, 6)),
('Itchy & Scratchy & Marge', datetime.date(1990, 12, 20)),
('Bart Gets Hit by a Car', datetime.date(1991, 1, 10)),
('One Fish, Two Fish, Blowfish, Blue Fish',
       datetime.date(1991, 1, 24)),
('The Way We Was', datetime.date(1991, 1, 31)),
('Homer vs. Lisa and the Eighth Commandment',
       datetime.date(1991, 2, 7)),
('Principal Charming', datetime.date(1991, 2, 14)),
('Oh Brother, Where Art Thou?', datetime.date(1991, 2, 21)),
("Bart's Dog Gets an F", datetime.date(1991, 3, 7)),
('Old Money', datetime.date(1991, 3, 28)),
('Brush With Greatness', datetime.date(1991, 4, 11)),
("Lisa's Substitute", datetime.date(1991, 4, 25)),
('The War of the Simpsons', datetime.date(1991, 5, 2)),
('Three Men and a Comic Book', datetime.date(1991, 5, 9)),
('Blood Feud', datetime.date(1991, 8, 11))},
  ...
}

Return type:

create_plot_year_tvdata.

howdy.tv.tv.get_tvdata_ordered_by_date(tvdata)

This flattens the TV data, stored as a nested dict (see documentation in get_library_data that focuses on the format of the dictionary for TV libraries) into a dictionary whose keys are the date at which episodes have been aired, and whose values are the list of episodes aired on that date. Each element of that list is a tuple representing a given episode: ( SHOW, SEASON #, EPISODE #, EPISODE TITLE ).

For example, let tvdata represent the Plex TV library information collected with get_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:: dict

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

get_shows_to_exclude.

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 a dict, 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 by return_error_raw.

As of November 14, 2025, here are the magnet link methods that work and don’t work when searching for "The Simpsons S31E01".

Table 5.1 Which TV Torrent Trackers or Services Work?
Torrent Service	Logo	Search Method	Does It Work?
EZTV.IO		`get_tv_torrent_eztv_io`	`False`
Zooqle		`get_tv_torrent_zooqle`	`True`
RARBG		`get_tv_torrent_rarbg`	`False`
Torrentz		`get_tv_torrent_torrentz`	`False`
KickAssTorrents		`get_tv_torrent_kickass`	`False`
The Pirate Bay		`get_tv_torrent_tpb`	`False`
Jackett torrent search		`get_tv_torrent_jackett`	`True`

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 or tuple of size at least 2. Here is its meaning if it is not None:
- if its size is 1, then the minimum size of H264 and H265/HEVC encoded videos, in MB, is minsizes[ 0 ].
- if its size is $\ge 2$, then the minimum size of H264 encoded video, in MB, is minsizes[ 0 ]. The minimum size of H265/HEVC encoded video, in MB, is minsizes[ 1 ].
maxsizes (list) –
optional list or tuple of size at least 2. Here is its meaning if it is not None:
- if its size is 1, then the maximum size of H264 and H265/HEVC encoded videos, in MB, is maxsizes[ 0 ].
- if its size is $\ge 2$, then the maximum size of H264 encoded video, in MB, is maxsizes[ 0 ]. The maximum size of H265/HEVC encoded video, in MB, is maxsizes[ 1 ].

Returns:

if successful, then returns a two member tuple the first member is a list 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 the date at which the magnet link was publshed and put online.

If this is unsuccessful, then returns an error tuple of the form returned by return_error_raw.

Return type:: tuple

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 in name 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 is False.

Returns:

if successful, then returns a two member tuple the first member is a list 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 by return_error_raw.

Return type:: tuple

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:

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.

Returns:

if successful, then returns a two member tuple the first member is a list 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 by return_error_raw.

Return type:: tuple

Warning

As of November 14, 2025, 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:

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.

Returns:

if successful, then returns a two member tuple the first member is a list 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 by return_error_raw.

Return type:: tuple

Warning

As of November 14, 2025, 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:

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.

Returns:

if successful, then returns a two member tuple the first member is a list 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 by return_error_raw.

Return type:: tuple

Warning

As of November 14, 2025, 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 a list 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 by return_error_raw.

Return type:: tuple

Warning

As of November 14, 2025, 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:

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$.
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 a list 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 by return_error_raw.

Return type:: tuple

howdy.tv.tv_torrents.return_error_couldnotfind(name)

Returns a tuple error message in the format of return_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 format return_error_raw, with the error message, "Failure, could not find any tv shows with search term <name>".
Return type:: str

See also

return_error_raw.

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 in create_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 using get_transmission_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. If False, 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 status dictionary 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 status dictionary 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:

See also

get_tv_batch.
get_remaining_episodes.
create_tvTorUnits.
download_batched_tvtorrent_shows.

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:

series_id (int) – the TMDB database series ID.
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 before date_now, then define the show as ended. By default, date_now is the current date.

Returns:

True if the show is “ended,” otherwise False.

Return type:

bool

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.

Parameters:

show (str) – name of the TV show in the tmdbshowids database.
firstAiredYear (int) – the year in which the show aired.

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 the str 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},
 ...
]

Parameters:

imdbID (str) – the IMDB ID of the TV show.
apiKey (str) – the OMDB API key.

Returns:

a list of IMDB episode information for the TV show.

Return type:

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 the date the episode aired, season is the season it aired, and episode is the episode number in that season.

Parameters:

tmdbID (int) – the TMDB series ID.
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 season 0 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 a tuple: the first element is the IMDB series ID, and the second element is a list of years during which the TV series has aired.

Parameters:

series_name (str) – the series name.
apikey (str) – the OMDB API key.

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: the id is the TMDB series ID, and airedYear is the year in which the first episode aired.

Parameters:

series_name (str) – the series name.
firstAiredYear (int) – optional argument. If provided, filter on TV shows that were first aired that year.
minmatch (float) – minimum value of the ratio match. Must be $> 0$ and $\le 100.0$. Default is 10.0.

Returns:

a list of candidate TMDB TV shows, otherwise None. 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.

Parameters:

series_name (str) – the series name.
apikey (str) – the OMDB API key.

Returns:

the IMDB key associated with series_name.

Return type:

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.

Parameters:

series_name (str) – the series name.
firstAiredYear (int) – optional argument. If provided, filter on TV shows that were first aired that year.
minmatch (float) – the minimal matching of the series name. Default is 50.0.

Returns:

the TMDB series ID for that TV show.

Return type:

int

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.

Parameters:

date (date) – the date after which to look for updated TV shws.
token (str) – the TVDB API access token.
verify (bool) – optional argument, whether to verify SSL connections. Default is True.

Returns:

a set of TVDB series IDs.

Return type:

set

howdy.tv.tv_attic.get_tot_epdict_imdb(showName, firstAiredYear=None)

Returns a summary nested dict of episode information for a given TV show, using Cinemagoer 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 a date.

An example of the structure of this dictionary can be found in get_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.

Returns:

a summary nested dict of episode information for a given TV show.

Return type:

See also

get_tot_epdict_tvdb.
get_tot_epdict_omdb.
get_tot_epdict_tmdb.

howdy.tv.tv_attic.get_tot_epdict_omdb(showName, apikey, inYear=None)

Returns a dict of episodes found from the OMDB 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 the episode names.

Parameters:

showName (str) – the series name.
apikey (str) – the OMDB API key.
inYear (int) – optional argument. If given, then search for those TV shows whose episodes aired in inYear.

Returns:

a dict of episode information for that TV show. For example, for The Simpsons (here the collection of episodes is incomplete),

{
{7: 'The Call of the Simpsons',
'The Telltale Head',
'Life on the Fast Lane',
"Homer's Night Out",
'The Crepes of Wrath',
'Krusty Gets Busted',
'Some Enchanted Evening'},
{1: 'Bart Gets an F',
'Simpson and Delilah',
'Treehouse of Horror',
'Two Cars in Every Garage and Three Eyes on Every Fish',
'Dead Putting Society',
'The Way We Was',
'Homer vs. Lisa and the 8th Commandment',
'Principal Charming',
'Oh Brother, Where Art Thou?',
"Bart's Dog Gets an F",
'Old Money',
'Brush with Greatness',
"Lisa's Substitute",
'The War of the Simpsons',
'Three Men and a Comic Book',
'Blood Feud'},
 ...
}

If unsuccessful, then returns None.

Return type:

See also

get_tot_epdict_imdb.
get_tot_epdict_tmdb.

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:

epURL (str) – the Wikipedia URL for the TV show.
seasnums (int) – the season number for which to get episodes.
verify (bool) – optional argument, whether to verify SSL connections. Default is True.

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 a date object). This two level dictionary has the same format as the output from get_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 season 0 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)),
('Bart the Genius', datetime.date(1990, 1, 14)),
("Homer's Odyssey", datetime.date(1990, 1, 21)),
("There's No Disgrace Like Home", datetime.date(1990, 1, 28)),
('Bart the General', datetime.date(1990, 2, 4)),
('Moaning Lisa', datetime.date(1990, 2, 11)),
('The Call of the Simpsons', datetime.date(1990, 2, 18)),
('The Telltale Head', datetime.date(1990, 2, 25)),
('Life on the Fast Lane', datetime.date(1990, 3, 18)),
("Homer's Night Out", datetime.date(1990, 3, 25)),
('The Crepes of Wrath', datetime.date(1990, 4, 15)),
('Krusty Gets Busted', datetime.date(1990, 4, 29)),
('Some Enchanted Evening', datetime.date(1990, 5, 13))},
  ...
}

If unsuccessful, then returns None.

Return type: