API

A small, clean and easy to use API for the thetvdb.com online DB service. It is designed to be fast, easy to use and to respect the functionality of the thetvdb.com API.

This module is the public interface for the package.

Usage:

>>> from pytvdbapi import api
>>> db = api.TVDB("B43FF87DE395DF56")
>>> search = db.search("How I met your mother", "en")
>>> show = search[0]
>>> show.SeriesName
'How I Met Your Mother'

class pytvdbapi.api.Episode(data, season)

Raise :TVDBAttributeError

Holds all information about an individual episode. This should be treated as a read-only object to obtain the attributes of the episode.

All episode values returned from thetvdb.com are accessible as attributes of the episode object. The attributes will be named exactly as returned from thetvdb.com and are case sensitive. TVDBAttributeError will be raised if accessing an invalid attribute. Some type conversions of the attributes will take place as follows:

• Strings of the format yyyy-mm-dd will be converted into a datetime.date object.
• Pipe separated strings will be converted into a list. E.g “foo | bar” => [“foo”, “bar”]
• Numbers with a decimal point will be converted to float
• A number will be converted into an int

It is possible to obtain the containing season through the Episode.season attribute.

Example:

>>> from pytvdbapi import api
>>> db = api.TVDB("B43FF87DE395DF56")
>>> search = db.search("Dexter", "en")
>>> show = search[0]
>>> episode = show[1][5]
>>> dir(episode) 
['Combined_episodenumber', 'Combined_season', 'DVD_chapter',
'DVD_discid', 'DVD_episodenumber', 'DVD_season', 'Director',
'EpImgFlag', 'EpisodeName', 'EpisodeNumber', 'FirstAired',
'GuestStars', 'IMDB_ID', 'Language', 'Overview', 'ProductionCode',
'Rating', 'RatingCount', 'SeasonNumber', 'Writer', 'absolute_number',
'filename', 'id', 'lastupdated', 'season', 'seasonid', 'seriesid']
>>> episode.EpisodeName
'Love American Style'
>>> episode.GuestStars 
['Terry Woodberry', 'Carmen Olivares', 'Ashley Rose Orr',
'Demetrius Grosse', 'Monique Curnen', 'June Angela',
'Valerie Dillman', 'Brad Henke', 'Jose Zuniga', 'Allysa Tacher',
'Lizette Carrion', 'Norma Fontana', 'Minerva Garcia',
'Josh Daugherty', 'Geoffrey Rivas']
>>> episode.FirstAired
datetime.date(2006, 10, 29)
>>> episode.season
<Season 001>

class pytvdbapi.api.Season(season_number, show)

Raise :TVDBIndexError

Holds all the episodes that belong to a specific season. It is possible to iterate over the Season to obtain the individual Episode instances. It is also possible to obtain an individual episode using the [ ] syntax. It will raise error.TVDBIndexError if trying to index an invalid episode index.

Example:

>>> from pytvdbapi import api
>>> db = api.TVDB("B43FF87DE395DF56")
>>> search = db.search("Dexter", "en")
>>> show = search[0]
>>> seson = show[1]
>>> season = show[1]
>>> len(season)
12
>>> season[3]
<Episode S001E003 - Popping Cherry>
>>> for episode in season:
...     print(episode)
...
<Episode S001E001 - Dexter>
<Episode S001E002 - Crocodile>
<Episode S001E003 - Popping Cherry>
<Episode S001E004 - Let's Give the Boy a Hand>
<Episode S001E005 - Love American Style>
<Episode S001E006 - Return to Sender>
<Episode S001E007 - Circle of Friends>
<Episode S001E008 - Shrink Wrap>
<Episode S001E009 - Father Knows Best>
<Episode S001E010 - Seeing Red>
<Episode S001E011 - Truth Be Told>
<Episode S001E012 - Born Free>

append(episode)

Parameters:episode (Episode) – The episode to append

Adds a new Episode to the season. If an episode with the same EpisodeNumber already exists, it will be overwritten.

class pytvdbapi.api.Show(data, api, language)

Raise :TVDBAttributeError, TVDBIndexError

Holds attributes about a single show and contains all seasons associated with a show. The attributes are named exactly as returned from thetvdb.com. This object should be considered a read only container of data provided from the server. Some type conversion of of the attributes will take place as follows:

• Strings of the format yyyy-mm-dd will be converted into a datetime.date object.
• Pipe separated strings will be converted into a list. E.g “foo | bar” => [“foo”, “bar”]
• Numbers with a decimal point will be converted to float
• A number will be converted into an int

The Show uses lazy evaluation and will only load the full data set from the server when this data is needed. This is to speed up the searches and to reduce the workload of the servers. This way, data will only be loaded when actually needed.

The Show supports iteration to iterate over the Seasons contained in the Show. You can also index individual seasons with the [ ] syntax.

Note

When searching, thetvdb.com provides a basic set of attributes for the show. When the full data set is loaded thetvdb.com provides a complete set of attributes for the show. The full data set is loaded when accessing the season data of the show. If you need access to the full set of attributes you can force the loading of the full data set by calling the update() function.

Example:

>>> from pytvdbapi import api
>>> db = api.TVDB("B43FF87DE395DF56")
>>> search = db.search("Dexter", "en")
>>> show = search[0]
>>> dir(show) 
['FirstAired', 'IMDB_ID', 'Overview', 'SeriesName', 'api', 'banner',
'id', 'lang', 'language', 'seasons', 'seriesid', 'zap2it_id']
>>> show.update()
>>> dir(show) 
['Actors', 'Airs_DayOfWeek', 'Airs_Time', 'ContentRating',
'FirstAired', 'Genre', 'IMDB_ID', 'Language', 'Network', 'NetworkID',
'Overview', 'Rating', 'RatingCount', 'Runtime', 'SeriesID',
'SeriesName', 'Status', 'added', 'addedBy', 'api', 'banner',
'fanart', 'id', 'lang',  'language', 'lastupdated', 'poster',
'seasons', 'seriesid', 'zap2it_id']
>>> len(show)
7
>>> show[5]
<Season 005>
>>> for season in show:
...     print(season)
...
<Season 000>
<Season 001>
<Season 002>
<Season 003>
<Season 004>
<Season 005>
<Season 006>

update()

Updates the data structure with data from the server.

class pytvdbapi.api.Search(result, search, language)

A search result returned from calling TVDB.search(). It supports iterating over the results, and the individual shows matching the search can be accessed using the [ ] syntax.

The search will contain 0 or more Show() instances matching the search.

The shows will be stored in the same order as they are returned from thetvdb.com. They state that if there is a perfect match to the search, it will be the first element returned.

Example:

>>> from pytvdbapi import api
>>> db = api.TVDB("B43FF87DE395DF56")
>>> search = db.search("Dexter", "en")
>>> for s in search:
...     print(s)
...
<Show - Dexter>
<Show - Cliff Dexter>

class pytvdbapi.api.TVDB(api_key, **kwargs)

Parameters:

• api_key – The API key to use to communicate with the server
• kwargs –

This is the main entry point for the API. The functionality of the API is controlled by configuring the key word arguments. The supported key word arguments are:

• force_lang (default=False). If set to True, the API will reload the

  language list from the server. If False, the local preloaded file will be used. The language list is relative stable but if there are changes it could be useful to set this to True to obtain a new version from the server. It is only necessary to do this once since the API stores the reloaded data for further use.

• cache_dir (default=/<system tmp dir>/pytvdbapi/). Specifies the directory to use for caching the server requests.

search(show, language, cache=True)

Parameters:

• show – The show name to search for
• language – The language abbreviation to search for. E.g. “en”
• cache – If False, the local cache will not be used and the resources will be reloaded from server.

Returns:

A Search() instance

Raise :

TVDBValueError

Searches the server for a show with the provided show name in the provided language. The language should be one of the supported language abbreviations or it could be set to all to search all languages. It will raise TVDBValueError if an invalid language is provided.

Searches are always cached within a session to make subsequent searches with the same parameters really cheap and fast. If cache is set to True searches will also be cached across sessions, this is recommended to increase speed and to reduce the workload of the servers.

Example:

>>> from pytvdbapi import api
>>> db = api.TVDB("B43FF87DE395DF56")
>>> search = db.search("Dexter", "en")
>>> for s in search:
...     print(s)
...
<Show - Dexter>
<Show - Cliff Dexter>