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 the ShowsToExclude 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.

Variables:	show – the show, that exists on the Plex server, to exclude from analysis and update. This is a `Column` containing a `String` object of size 65536.

howdy.tv.check_tvdb_api(username, apikey, userkey, verify=True)¶

Checks whether the TVDB API credentials are valid.

Parameters:	username (str) – the TVDB API user name. 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:	`True` if the credentials are valid, `False` otherwise.
Return type:	bool

See also

get_token.

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:	verify (bool) – optional argument, whether to verify SSL connections. Default is `True`. data (dict) – optional argument. If provided, must be a dictionary containing the TVDB API credentials as described in `get_tvdb_api`.
Returns:	the TVDB API token, otherwise returns `None` if there are errors.
Return type:	str

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

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

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.

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 January 03, 2021, 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`

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.