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
...
Bases: object
Representing a language that is supported by the API.
See also
TVDB.get_series(), TVDB.get_episode() and TVDB.search() for functions where the language can be specified.
This is what should be passed when specifying a language to the API.
The localised name of the language.
| Returns: | A list of Language objects |
|---|
Returns 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)>
...
| 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:
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.
New in version 0.5.
| Parameters: | key – A callable taking an Episode instance as argument and returns a boolean |
|---|---|
| Returns: | A list of 0 or more Episode instances |
Finds all Episode instances for witch key returns True.
See also
Season.filter() for information on filtering episodes in a specific season
New in version 0.5.
| Parameters: | key – A callable taking an Episode instance as argument and returns a boolean |
|---|---|
| Returns: | An Episode instance or None |
Finds the first Episode for witch key returns True.
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
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.
Updates the data structure with data from the server.
| 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 raise pytvdbapi.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
| Parameters: | episode_instance (Episode) – The episode_instance to append |
|---|
Adds a new Episode to the season. If an episode_instance with the same EpisodeNumber already exists, it will be overwritten.
| 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:
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']
| 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
| Parameters: |
|
|---|
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:
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.
| Parameters: |
|
|---|---|
| Returns: | A Search() instance |
| Raise: |
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>
...
New in version 0.4.
Changed in version 0.5: Added id_type parameter
| Parameters: |
|
|---|---|
| Returns: | A Show() instance |
| Raise: |
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
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: |
|
|---|---|
| Returns: | An Episode() instance |
| Raise: |
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 and pytvdbapi.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 using get_episode() the season attribute used to link the episode with a season will be None.
New in version 0.5.
| Parameters: |
|
|---|---|
| Returns: | If found, an Episode instance |
| Raise: |
Note
When the Episode() is loaded using get_episode_by_air_date() the season attribute used to link the episode with a season will be None.