Usage#

The central object is the TVDBClient client which needs the username, user_key, and api_key supplied by the TVDB. It can be initialised with a cache (optionally), and if no cache is passed a dummy cache object will be created.

Note

It is advisable to use a cache that will persist during a server restart, so that the token will not have to be regenerated.

Warning

Please be advised that the token will be stored in the default cache in plaintext, so if there are any security considerations they should be taken care into account when choosing the cache.

class tvdb_api_client.TVDBClient#

The TVDB client

__init__(username, user_key, api_key, cache=None, language=None)#
Parameters:

  • username (str) – The TVDB username

  • user_key (str) – The TVDB user key

  • api_key (str) – The TVDB api key

  • cache – The caching object to be used

  • language (str) – The 2-letter language code

Initialise the TVDB client

get_series_by_id(tvdb_id, *, refresh_cache=False, language=None)#
Parameters:

  • tvdb_id (str | int) – The TVDB id of the series

  • refresh_cache (bool) – Whether to use or not cached responses

  • language (str) – The 2-letter code, if overriding the client’s language is needed

Returns:

A dictionary of the series info

Return type:

dict

Get the series info by its tvdb id

get_series_by_imdb_id(imdb_id, *, refresh_cache=False, language=None)#
Parameters:

  • imdb_id (str) – The imdb id of the series

  • refresh_cache (bool) – Whether to use or not cached responses

  • language (str) – The 2-letter code, if overriding the client’s language is needed

Returns:

A dictionary of the series info

Return type:

dict

Get the series info by its imdb id

find_series_by_name(series_name, *, refresh_cache=False, language=None)#
Parameters:

  • series_name (str) – The series’ name

  • refresh_cache (bool) – Whether to use or not cached responses

  • language (str) – The 2-letter code, if overriding the client’s language is needed

Returns:

A list of all the series that match the name

Return type:

list[dict]

Find all TV series that match a TV series name

The info returned for each TV series are its name, the original air date (in “%Y-%m-%d” format) and the tvdb_id (as an integer).

This information should be enough to identify the desired series and search by id afterwards.

get_episodes_by_series(tvdb_id: str | int, *, refresh_cache=False, language=None)#
Parameters:

  • tvdb_id (str | int) – The TVDB id of the series

  • refresh_cache (bool) – Whether to use or not cached responses

  • language (str) – The 2-letter code, if overriding the client’s language is needed

Returns:

A list of all the episodes

Return type:

list[dict]

Get all the episodes for a TV series

Note

Also, all of these methods will used the cached value if present. To get new data, you may pass refresh_cache=True to all of them.