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.

  • 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.

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.

  • 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.

the TVDB API token, otherwise returns None if there are errors.

Return type:



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.

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

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.

  • 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.

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.

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 eztv_logo_image get_tv_torrent_eztv_io False
Zooqle zooqle_logo_image get_tv_torrent_zooqle True
RARBG rarbg_logo_image get_tv_torrent_rarbg False
Torrentz torrentz_logo_image get_tv_torrent_torrentz False
KickAssTorrents kickass_torrents_logo_image get_tv_torrent_kickass False
The Pirate Bay
get_tv_torrent_tpb False
Jackett torrent search jackett_logo_image 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.