api
Module¶
This is the main module for pytvdbapi intended for client usage. It contains functions to access the
API functionality through the TVDB
class and its methods. It has implementations for
representations of Show
, Season
and Episode
objects.
It also contains functionality to access the list of API supported languages through the languages()
function.
Basic usage:
>>> from pytvdbapi import api
>>> db = api.TVDB("B43FF87DE395DF56")
>>> result = db.search("How I met your mother", "en")
>>> len(result)
1
>>> show = result[0] # If there is a perfect match, it will be the first
>>> print(show.SeriesName)
How I Met Your Mother
>>> len(show) # Show the number of seasons
10
>>> for season in show:
... for episode in season:
... print(episode.EpisodeName)
...
Robin Sparkles Music Video - Let's Go to the Mall
Robin Sparkles Music Video - Sandcastles In the Sand
...
Pilot
Purple Giraffe
Sweet Taste of Liberty
Return of the Shirt
...
Languages¶
-
class
pytvdbapi.api.
Language
(abbrev, name, language_id)¶ Bases:
object
Representing a language that is supported by the API.
See also
TVDB.get_series()
,TVDB.get_episode()
andTVDB.search()
for functions where the language can be specified.-
abbreviation
= None¶ This is what should be passed when specifying a language to the API.
-
name
= None¶ The localised name of the language.
-
-
pytvdbapi.api.
languages
()¶ Returns: A list of Language
objectsReturns the list of all API supported languages.
Example:
>>> from pytvdbapi import api >>> for language in api.languages(): ... print(language) <Language - čeština(cs)> <Language - Dansk(da)> <Language - Deutsch(de)> ... <Language - English(en)> ... <Language - Svenska(sv)> ...
Show, Season and Episode Representation¶
-
class
pytvdbapi.api.
Show
(data, api, language, config, full_data=None)¶ Raise: pytvdbapi.error.TVDBAttributeError
,pytvdbapi.error.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.
Example:
>>> from pytvdbapi import api >>> db = api.TVDB("B43FF87DE395DF56") >>> result = db.search("dexter", "en") >>> show = result[0] >>> dir(show) # List the set of basic attributes ['AliasNames', 'FirstAired', 'IMDB_ID', 'Network', 'Overview', 'SeriesName', 'actor_objects', 'api', 'banner', 'banner_objects', 'id', 'lang', 'language', 'seriesid', 'zap2it_id'] >>> show.update() # Load the full data set from the server >>> dir(show) # List the full set of attributes ['Actors', 'Airs_DayOfWeek', 'Airs_Time', 'AliasNames', 'ContentRating', 'FirstAired', 'Genre', 'IMDB_ID', 'Language', 'Network', 'NetworkID', 'Overview', 'Rating', 'RatingCount', 'Runtime', 'SeriesID', 'SeriesName', 'Status', 'actor_objects', 'added', 'addedBy', 'api', 'banner', 'banner_objects', 'fanart', 'id', 'lang', 'language', 'lastupdated', 'poster', 'seriesid', 'tms_wanted_old', 'zap2it_id']
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.-
filter
(key)¶ New in version 0.5.
Parameters: key – A callable taking an Episode
instance as argument and returns a booleanReturns: A list of 0 or more Episode
instancesFinds all
Episode
instances for witchkey
returnsTrue
.See also
Season.filter()
for information on filtering episodes in a specific season
-
find
(key)¶ New in version 0.5.
Parameters: key – A callable taking an Episode
instance as argument and returns a booleanReturns: An Episode
instance or NoneFinds the first
Episode
for witchkey
returnsTrue
.Note
The order in which the
Episode
instances are searched is not guaranteed and the first match found is not necessarily the first one in a chronological sense.See also
Season.find()
for information on finding an episode in a specific season
-
load_actors
()¶ New in version 0.4.
Loads the extended actor information into a list of
pytvdbapi.actor.Actor
objects. They are available through the actor_objects attribute of the show.If you have used the actors=True keyword when creating the
TVDB
instance the actors will be loaded automatically and there is no need to use this function.See also
TVDB
for information on how to use the actors keyword argument.
New in version 0.4.
Loads the extended banner information into a list of
pytvdbapi.banner.Banner
objects. They are available through the banner_objects attribute of the show.If you have used the banners=True keyword when creating the
TVDB
instance the banners will be loaded automatically and there is no need to use this function.See also
TVDB
for information on how to use the banners keyword argument.
-
update
()¶ Updates the data structure with data from the server.
- Strings of the format yyyy-mm-dd will be converted into a
-
class
pytvdbapi.api.
Season
(season_number, show)¶ Raise: pytvdbapi.error.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 raisepytvdbapi.error.TVDBIndexError
if trying to index an invalid episode index.It is possible to obtain the containing
Show
instance through the Season.show attribute.Example:
>>> from pytvdbapi import api >>> db = api.TVDB("B43FF87DE395DF56") >>> result = db.search("Dexter", "en") >>> show = result[0] >>> season = show[2] >>> len(season) # Number of episodes in the season 12 >>> print(season.season_number) 2 >>> print(season[2].EpisodeName) Waiting to Exhale >>> for ep in season: ... print(ep.EpisodeName) ... It's Alive! Waiting to Exhale An Inconvenient Lie See-Through ... Left Turn Ahead The British Invasion
-
append
(episode_instance)¶ Parameters: episode_instance ( Episode
) – The episode_instance to appendAdds a new
Episode
to the season. If an episode_instance with the same EpisodeNumber already exists, it will be overwritten.
-
-
class
pytvdbapi.api.
Episode
(data, season, config)¶ Raise: pytvdbapi.error.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. 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") >>> result = db.search("Dexter", "en") >>> show = result[0] >>> episode = show[1][2] # Get episode S01E02 >>> print(episode.season) <Season 001> >>> print(episode.EpisodeNumber) 2 >>> print(episode.EpisodeName) Crocodile >>> episode.FirstAired datetime.date(2006, 10, 8) >>> 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', 'thumb_added', 'thumb_height', 'thumb_width']
- Strings of the format yyyy-mm-dd will be converted into a
API Access¶
-
class
pytvdbapi.api.
Search
(result, search_phrase, language)¶ Raise: pytvdbapi.error.TVDBIndexError
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.
See also
TVDB.search()
for an example of how to use the search
-
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 keyword arguments. The supported keyword arguments are:
- cache_dir (default=/<system tmp dir>/pytvdbapi/). Specifies the directory to use for caching the server requests.
New in version 0.3.
actors (default=False) The extended actor information is stored in a separate XML file and would require an additional request to the server to obtain. To limit the resource usage, the actor information will only be loaded when explicitly requested.
Note
The
Show()
object always contain a list of actor names.banners (default=False) The extended banner information is stored in a separate XML file and would require an additional request to the server to obtain. To limit the resource usage, the banner information will only be loaded when explicitly requested.
New in version 0.4.
- ignore_case (default=False) If set to True, all attributes on the
Show
andEpisode
instances will be accessible in a case insensitive manner. If set to False, the default, all attributes will be case sensitive and retain the same casing as provided by thetvdb.com. - timeout (default=None) When set to a number, will cause the http
request to timeout after that number of seconds.
-
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()
instanceRaise: 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
pytvdbapi.error.TVDBValueError
if an invalid language is provided.Searches are always cached within a session to make subsequent searches with the same parameters 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") >>> result = db.search("House", "en") >>> print(result[0]) <Show - House> >>> for show in result: ... print(show) <Show - House> ...
-
get_series
(series_id, language, id_type='tvdb', cache=True)¶ New in version 0.4.
Changed in version 0.5: Added id_type parameter
Parameters: - series_id – The Show Id to fetch
- language – The language abbreviation to search for. E.g. “en”
- id_type – Information about what kind of id is provided. Should be one of (‘tvdb’, ‘imdb’, ‘zap2it’)
- cache – If False, the local cache will not be used and the resources will be reloaded from server.
Returns: A
Show()
instanceRaise: Provided a valid Show ID, the data for the show is fetched and a corresponding
Show()
object is returned.Example:
>>> from pytvdbapi import api >>> db = api.TVDB("B43FF87DE395DF56") >>> show = db.get_series( 79349, "en" ) # Load Dexter >>> print(show.SeriesName) Dexter
-
get_episode
(self, language, method="id", cache=True, **kwargs)¶ New in version 0.4.
Changed in version 0.5: Added the possibility to get an episode using default, dvd, and absolute sort order
Parameters: - episode_id – Deprecated in 0.5 Use the episodeid keyword argument with the id method instead
- 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.
- method – (default=id) Specify what method should be used to get the episode. Depending on what method is specified, different parameters must be passed as keyword arguments. Should be one of (id, default, dvd, absolute).
- kwargs – episodeid, seriesid, seasonnumber, episodenumber and absolutenumber. See the examples for information on how to use them.
Returns: An
Episode()
instanceRaise: Retrieves a single episode. Depending on what method is specified different criteria can be used to retrieve the episode.
Examples:
Load an episode using the episode id
>>> from pytvdbapi import api >>> db = api.TVDB("B43FF87DE395DF56") >>> ep = db.get_episode("en", episodeid=308834) # id is the default method >>> print(ep.EpisodeName) Crocodile
Load an episode using dvd and default sort order
>>> ep = db.get_episode("en", "dvd", seasonnumber=2, episodenumber=5, seriesid=79349) >>> print(ep.EpisodeName) The Dark Defender
>>> ep = db.get_episode("en", "default", seasonnumber=2, episodenumber=6, seriesid=79349) >>> print(ep.EpisodeName) Dex, Lies, and Videotape
Load an episode using the absolute number
>>> ep = db.get_episode("en", "absolute", absolutenumber=19, seriesid=79349) >>> print(ep.EpisodeName) That Night, A Forest Grew
Under some circumstances the backend server fails to return a proper 404 file not found error response when the requested episode can not be found, but instead returns a valid HTML file with the content 404 file not found. For this reason it is required to check for both
pytvdbapi.error.TVDBValueError
andpytvdbapi.error.BadData
to detect an issue downloading the episode.>>> from pytvdbapi.error import BadData >>> from pytvdbapi.error import TVDBNotFoundError >>> try: ... ep = db.get_episode("en", episodeid=308834) ... except TVDBNotFoundError: ... # this is the standard 404 error code returned from the server ... pass ... except BadData: ... # This is when the server returns a 200 code but with a HTML page saying 404 Nothing found ... pass
Note
When the
Episode()
is loaded usingget_episode()
the season attribute used to link the episode with a season will be None.
-
get_episode_by_air_date
(self, series_id, air_date, cache=True)¶ New in version 0.5.
Parameters: - series_id – The TVDB series id of the episode
- language – The language to search for. Should be a two letter abbreviation e.g. en.
- air_date (datetime.date) – The air date to search for. Should be of type
datetime.date
- cache – If False, the local cache will not be used and the resources will be reloaded from server.
Returns: If found, an
Episode
instanceRaise: Note
When the
Episode()
is loaded usingget_episode_by_air_date()
the season attribute used to link the episode with a season will be None.