pytvdbapi Documentation Release 0.5.0
Björn Larsson
February 23, 2016
Contents
I Basics 3
1 Basics 5 1.1 Getting Started...... 5 1.1.1 About...... 5 1.1.2 Installing...... 5 1.1.3 Dependencies...... 5 1.1.4 Supported Versions...... 5 1.1.5 Known Issues...... 6 1.2 Python 2.X and 3.X...... 6 1.2.1 Unicode Vs. Str...... 6 1.3 Examples...... 7 1.3.1 Basic Usage...... 7 1.3.2 Working with a show object...... 7 1.3.3 Working with a Season object...... 8 1.3.4 Working with an episode object...... 8 1.3.5 Searching and Filtering...... 9 1.3.6 Case insensitive attributes...... 9 1.3.7 Working with Actor and Banner Objects...... 10 1.3.8 Handle Network Issues...... 11
II Modules 13
2 pytvdbapi modules 15 2.1 api Module...... 15 2.1.1 Languages...... 15 2.1.2 Show, Season and Episode Representation...... 16 2.1.3 API Access...... 20 2.2 actor Module...... 23 2.3 banner Module...... 24 2.4 error Module...... 26
III Extras 27
3 License 29
4 Credits 31 4.1 Contributors...... 31
i 5 Contact 33 5.1 Feedback / Suggestions...... 33 5.2 Twitter...... 33
IV Indices and tables 35
Python Module Index 39
ii pytvdbapi Documentation, Release 0.5.0
Welcome to the documentation for pytvdbapi version 0.5.0
Contents 1 pytvdbapi Documentation, Release 0.5.0
2 Contents Part I
Basics
3
CHAPTER 1
Basics
1.1 Getting Started
1.1.1 About pytvdbapi is created to be an easy to use and intuitive Python API for the TV-Show database thetvdb.com. It is designed with the intention of making it easier and faster to develop applications using data from thetvdb.com, without having to bother about working with the raw data provided.
1.1.2 Installing
The best and recommended way to install pytvdbapi is to use pip. To install, issue the following command in a shell: $ pip install pytvdbapi
Depending on on what system and where you install pytvdbapi you may need root privileges to perform the above command.
1.1.3 Dependencies pytvdbapi depends on the following external packages: • httplib2 If you install using the above description, the dependencies will be installed for you if you do not already have them on your system.
1.1.4 Supported Versions
The following python versions are supported by pytvdbapi. • 2.6 • 2.7 • 3.3 • 3.4 It may work on other Python versions but they are not actively supported and tested against.
5 pytvdbapi Documentation, Release 0.5.0
1.1.5 Known Issues
The following issues/problems with pytvdbapi are known. • No support for connections through proxy servers.
1.2 Python 2.X and 3.X
This section describes differences in using pytvdbapi in a Python 2.X environment and a Python 3.X environment. In particular it describes the differences and changes regarding unicode handling.
1.2.1 Unicode Vs. Str
In python 3, the unicode object has been removed and the standard str type always represent a unicode string 1. Internally pytvdbapi works exclusively with unicode. That means that on Python 2.X all text attributes will be of type unicode and on Python 3 they will be of type str, all text attributes will be automatically converted as they are loaded. >>> from pytvdbapi import api >>> import sys >>> db= api.TVDB('B43FF87DE395DF56') >>> result= db.search('Alarm für cobra 11','de')
>>> show= result[0]
>>> if sys.version<'3': ... assert type(show.SeriesName) is unicode ... else: ... assert type(show.SeriesName) is str
pytvdbapi attempts to convert all text parameters passed into unicode, that means unicode on Python 2.X and str on python 3.X. For example, both of these are valid: >>> from pytvdbapi import api >>> db= api.TVDB('B43FF87DE395DF56')
>>> result= db.search('Alarm für cobra 11','de') >>> len(result) 3 >>> print(result[0])
And: >>> result= db.search(u'Dexter','de') >>> len(result) 3 >>> print(result[0])
1 https://docs.python.org/3.3/howto/unicode.html
6 Chapter 1. Basics pytvdbapi Documentation, Release 0.5.0
1.3 Examples
This section provides some different examples of how pytvdbapi can be used.
1.3.1 Basic Usage
Search for a show, given its name and a language: >>> from pytvdbapi import api >>> db= api.TVDB("B43FF87DE395DF56") >>> result= db.search("Dexter","en") >>> show= result[0] # If there is a perfect match, it will be the first
>>> print(show.SeriesName) Dexter >>> print(show.FirstAired) 2006-10-01
You can easily loop all episodes in a show: >>> for season in show: ... for episode in season: ... print(u"{0} - {1}".format(episode.EpisodeName, episode.FirstAired)) ... Early Cuts: Alex Timmons (Chapter 1) - 2009-10-25 ... Finding Freebo - 2008-10-05 The Lion Sleeps Tonight - 2008-10-12 All In the Family - 2008-10-19 Turning Biminese - 2008-10-26 ... Dress Code - 2013-08-11 Are We There Yet? - 2013-08-18 Make Your Own Kind of Music - 2013-08-25 Goodbye Miami - 2013-09-08 Monkey In a Box - 2013-09-15 Remember the Monsters? - 2013-09-22
1.3.2 Working with a show object
Basic usage: # You can use slicing to only get a sub set of all seasons >>> for season in show[2:5]: ... print(season.season_number) ... 2 3 4
# List the total number of seasons # Season 0 is the "specials" season containing special episodes >>> len(show) 9
1.3. Examples 7 pytvdbapi Documentation, Release 0.5.0
>>> print(show[2]) # Access a particular season
Access show attributes: >>> print(show.IMDB_ID) tt0773262
>>> hasattr(show,'foo') False
>>> hasattr(show,'Genre') True
>>> getattr(show,'foo',-1) -1
1.3.3 Working with a Season object
Episode access: >>> from pytvdbapi.error import TVDBIndexError >>> season= show[2] # Grab a specific season, season 0 is the specials season
>>> len(season) # The number of episodes in the season 12
>>> try: ... print(season[0]) ... except TVDBIndexError: ... # Episodes start at index 1 ... print('No episode at index 0') No episode at index 0
>>> print(season[3])
You can use slicing to access specific episode objects: >>> for episode in season[3:10:2]: ... print(episode.EpisodeNumber) ... 4 6 8 10
Access the associated show: >>> season.show
1.3.4 Working with an episode object
Accessing episode attributes:
8 Chapter 1. Basics pytvdbapi Documentation, Release 0.5.0
>>> episode= show[2][4] >>> print(episode.EpisodeName) See-Through
>>> hasattr(episode,'foo') False
>>> hasattr(episode,'Director') True
Access the containing season: >>> episode.season
1.3.5 Searching and Filtering
It is possible to search and filter a show or season instance to find all episodes matching a certain criteria. Searching for all shows written by Tim Schlattmann: >>> episodes= show.filter(key= lambda ep: ep.Writer =='Tim Schlattmann') >>> len(episodes) 7
>>> for ep in episodes: ... print(ep.EpisodeName) ... The Dark Defender Turning Biminese Go Your Own Way Dirty Harry First Blood Once Upon a Time... Scar Tissue
Find the episode with production code 302: >>> episode= show.find(key= lambda ep: ep.ProductionCode==302) >>> print(episode.EpisodeName) Finding Freebo
>>> print(episode.ProductionCode) 302
1.3.6 Case insensitive attributes
It is possible to tell the API to ignore casing when accessing the objects dynamic attributes. If you pass ignore_case=True when creating the pytvdbapi.api.TVDB instance, you can access the dynamically cre- ated attributes of the pytvdbapi.api.Show, pytvdbapi.api.Season, pytvdbapi.api.Episode, pytvdbapi.actor.Actor and pytvdbapi.banner.Banner instances in a case insensitive manner. Example: >>> from pytvdbapi import api >>> db= api.TVDB("B43FF87DE395DF56", ignore_case=True) # Tell API to ignore case >>> result= db.search("Dexter","en")
1.3. Examples 9 pytvdbapi Documentation, Release 0.5.0
>>> show= result[0]
>>> print(show.seriesname) Dexter
>>> hasattr(show,'SERIESNAME') True >>> hasattr(show,'seriesname') True >>> hasattr(show,'sErIeSnAmE') True
>>> episode= show[3][5] >>> print(episode.episodename) Turning Biminese
>>> hasattr(episode,'EPISODENAME') True >>> hasattr(episode,'episodename') True
1.3.7 Working with Actor and Banner Objects
By default, the extended information for pytvdbapi.actor.Actor and pytvdbapi.banner.Banner are not loaded. This is to save server resources and avoid downloading data that is not necessarily needed. The pytvdbapi.api.Show always contain a list of actor names. If you do want to use this extra actor and banner data you can pass actors=True and banners=True respectively when creating the pytvdbapi.api.TVDB instance, this will cause the actors and/or banners to be loaded for all shows. If you only want this information for some shows, you can use the pytvdbapi.api.Show.load_actors() and pytvdbapi.api.Show.load_banners() functions instead. Using keyword arguments: >>> from pytvdbapi import api >>> db= api.TVDB("B43FF87DE395DF56", actors=True, banners=True) >>> result= db.search("Dexter","en") >>> show= result[0] >>> show.update()
>>> print(show.actor_objects[0])
Using instance functions: >>> from pytvdbapi import api >>> db= api.TVDB("B43FF87DE395DF56") >>> result= db.search("Dexter","en") >>> show= result[0]
>>> len(show.actor_objects) 0 >>> len(show.banner_objects) 0
>>> show.load_actors() # Load actors >>> assert len(show.actor_objects)>0
10 Chapter 1. Basics pytvdbapi Documentation, Release 0.5.0
>>> print(show.actor_objects[0])
>>> show.load_banners() # Load banners
1.3.8 Handle Network Issues
This provides a more complete example of how to handle the fact that there could be something wrong with the connection to the backend, or the backend could be malfunctioning and return invalid data that we can not work with. >>> from pytvdbapi import api >>> from pytvdbapi.error import ConnectionError, BadData, TVDBIndexError >>> db= api.TVDB("B43FF87DE395DF56")
>>> try: ... result= db.search("Dexter","en") # This hits the network and could raise an exception ... show= result[0] # Find the show object that you want ... show.update() # this loads the full data set and could raise exceptions ... except TVDBIndexError: ... # The search did not generate any hits ... pass ... except ConnectionError: ... # Handle the fact that the server is not responding ... pass ... except BadData: ... # The server responded but did not provide valid XML data, handle this issue here, ... # maybe by trying again after a few seconds ... pass ... else: ... # At this point, we should have a valid show instance that we can work with. ... name= show.SeriesName
1.3. Examples 11 pytvdbapi Documentation, Release 0.5.0
12 Chapter 1. Basics Part II
Modules
13
CHAPTER 2
pytvdbapi modules
2.1 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 ...
2.1.1 Languages class pytvdbapi.api.Language(abbrev, name, language_id) Bases: object
15 pytvdbapi Documentation, Release 0.5.0
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. 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 objects Returns the list of all API supported languages. Example: >>> from pytvdbapi import api >>> for language in api.languages(): ... print(language)
2.1.2 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")
16 Chapter 2. pytvdbapi modules pytvdbapi Documentation, Release 0.5.0
>>> 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 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 find(key) 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 load_actors() New in version 0.4. Loads the extended actor information into a list of pytvdbapi.actor.Actor objects. They are avail- able 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.
2.1. api Module 17 pytvdbapi Documentation, Release 0.5.0
See also: TVDB for information on how to use the actors keyword argument. load_banners() 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. 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 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
append(episode_instance) 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.
18 Chapter 2. pytvdbapi modules pytvdbapi Documentation, Release 0.5.0
filter(key) New in version 0.5. Parameters key – A callable taking an Episode instance as argument and returns a boolean Raises pytvdbapi.error.TypeError Returns list with 0 or more Episode instances Return a list of all Episode instances for witch key returns True find(key) New in version 0.5. Parameters key – A callable taking an Episode instance as argument and returns a boolean Raises pytvdbapi.error.TypeError Returns An Episode instance or None if no match was found Return the first Episode for witch key returns True 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. TVDBAttribu- teError 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)
>>> print(episode.EpisodeNumber) 2
>>> print(episode.EpisodeName) Crocodile
>>> episode.FirstAired datetime.date(2006, 10, 8)
>>> dir(episode) ['Combined_episodenumber',
2.1. api Module 19 pytvdbapi Documentation, Release 0.5.0
'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']
2.1.3 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=/
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 and Episode 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.
20 Chapter 2. pytvdbapi modules pytvdbapi Documentation, Release 0.5.0
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 pytvdbapi.error.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 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])
>>> for show in result: ... print(show)
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() instance Raise pytvdbapi.error.TVDBValueError, pytvdbapi.error.TVDBIdError 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
2.1. api Module 21 pytvdbapi Documentation, Release 0.5.0
>>> 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() instance Raise pytvdbapi.error.TVDBValueError, pytvdbapi.error.BadData 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.
22 Chapter 2. pytvdbapi modules pytvdbapi Documentation, Release 0.5.0
>>> 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.
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 instance Raise pytvdbapi.error.TVDBValueError
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.
2.2 actor Module
A module for actor related functionality. class pytvdbapi.actor.Actor(mirror, data, show) Representing an Actor as provided by thetvdb.com. It Will contain all attributes as delivered from thetvdb.com, the attributes are described in more detail here. Example: >>> from pytvdbapi import api >>> db= api.TVDB("B43FF87DE395DF56") >>> result= db.search("dexter","en") >>> show= result[0]
>>> show.load_actors()
>>> actor= show.actor_objects[0] >>> print(actor.image_url)
2.2. actor Module 23 pytvdbapi Documentation, Release 0.5.0
http://thetvdb.com/banners/actors/70947.jpg
>>> for actor in show.actor_objects: ... print(u"{0} - {1}".format(actor.Name, actor.Role)) ... Michael C. Hall - Dexter Morgan Jennifer Carpenter - Debra Morgan James Remar - Harry Morgan ... Jimmy Smits - Miguel Prado Jaime Murray - Lila Tournay John Lithgow - Arthur Mitchell ...
Additional class attributes are: pytvdbapi.actor.Actor.image_url The full URL for the actor image.
2.3 banner Module
A module for managing banner information Although some banners are related to a specific season, all banners will be stored as a property of the related Show instance. class pytvdbapi.banner.Banner(mirror, data, show) Bases: object Representing a Banner as provided by thetvdb.com. More information about the data provided for a Banner can be found here. Attributes: The number and types of attributes that the Banner has is dependent on the type of Banner it is. Below is a description of the different attributes. Note: Wherever ‘text’ is given as the attribute type, this means that on Python 2.X it will be of type unicode and on Python 3.X str. Common: These attributes are present for all Banner objects. •BannerPath (text). The last part of the URL pointing to the image. This is appended to the correct mirror address to form the full URL. •BannerType (text). This could be any of fanart, season or poster. This value controls what other attributes are available as described below. •BannerType2 (text). What this attribute contains will depend on the type of Banner and will be described in each sub section below. •Language (text). •Rating (float). •RatingCount (int). •id (int). •banner_url (text). This is generated by pytvdbapi and is the full URL for the banner.
24 Chapter 2. pytvdbapi modules pytvdbapi Documentation, Release 0.5.0
fanart: Additional to the common attributes, the following attributes are included on objects of type fanart. •BannerType2 (text). Contains the dimension of the image as text. •Colors (list). •SeriesName (bool). •ThumbnailPath (text). •VignettePath (text). poster: poster type does not contain any additional attributes. •BannerType2 (text). Contains the dimension of the image as a string. season: Additional to the common attributes, the following attributes are included on objects of type season. •BannerType2 (text). Contains the word ‘season’ •Season (int). Example: >>> from pytvdbapi import api >>> db= api.TVDB('B43FF87DE395DF56', banners=True) >>> show= db.get_series( 79349,"en") # Dexter >>> show.update()
>>> assert len(show.banner_objects)>0 >>> banner= show.banner_objects[0]
>>> print(banner.banner_url) http://thetvdb.com/banners/fanart/original/79349-...jpg
>>> print(banner.Language) en
Showing the different banner types and their attributes.
>>> fanart= [b for b in show.banner_objects if b.BannerType =="fanart"] >>> dir(fanart[0]) ['BannerPath', 'BannerType', 'BannerType2', 'Colors', 'Language', 'Rating', 'RatingCount', 'SeriesName', 'ThumbnailPath', 'VignettePath', 'banner_url', 'id']
>>> print(fanart[0].BannerType2) 1280x720
>>> posters= [b for b in show.banner_objects if b.BannerType =="poster"] >>> dir(posters[0]) ['BannerPath', 'BannerType', 'BannerType2', 'Language', 'Rating', 'RatingCount', 'banner_url', 'id']
>>> print(posters[0].BannerType2) 680x1000
2.3. banner Module 25 pytvdbapi Documentation, Release 0.5.0
>>> seasons= [b for b in show.banner_objects if b.BannerType =="season"] >>> dir(seasons[0]) ['BannerPath', 'BannerType', 'BannerType2', 'Language', 'Rating', 'RatingCount', 'Season', 'banner_url', 'id']
>>> print(seasons[0].BannerType2) season
2.4 error Module
A module containing all the exceptions raised by pytvdbapi. pytvdbapi will only raise exceptions that are of type PytvdbapiError or it’s subclasses. exception pytvdbapi.error.PytvdbapiError(msg, *args, **kwargs) Bases: exceptions.Exception Base exception for all exceptions raised by pytvdbapi exception pytvdbapi.error.BadData(msg, *args, **kwargs) Bases: pytvdbapi.error.PytvdbapiError Raised if there are issues parsing the XML data provided by thetvdb.com Usualy a BadData exception is the result of a malfunctioning backend server. The problem is that the server returns a 200 - OK status code but fails to provide valid data in the response. exception pytvdbapi.error.ConnectionError(msg, *args, **kwargs) Bases: pytvdbapi.error.PytvdbapiError Raised by the pytvdbapi.Loader when unable to connect to the provided URL. exception pytvdbapi.error.TVDBAttributeError(msg, *args, **kwargs) Bases: pytvdbapi.error.PytvdbapiError, exceptions.AttributeError A replacement for the standard AttributeError. exception pytvdbapi.error.TVDBIndexError(msg, *args, **kwargs) Bases: pytvdbapi.error.PytvdbapiError, exceptions.IndexError A replacement for the standard IndexError. exception pytvdbapi.error.TVDBIdError(msg, *args, **kwargs) Bases: pytvdbapi.error.PytvdbapiError Raised when trying to get a show using an invalid Show ID exception pytvdbapi.error.TVDBValueError(msg, *args, **kwargs) Bases: pytvdbapi.error.PytvdbapiError, exceptions.ValueError A replacement for the standard ValueError exception. exception pytvdbapi.error.TVDBNotFoundError(msg, *args, **kwargs) Bases: pytvdbapi.error.PytvdbapiError Raised when the data can not be found. Represent the 404 http code.
26 Chapter 2. pytvdbapi modules Part III
Extras
27
CHAPTER 3
License
Copyright 2011 - 2013, Björn Larsson This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program. If not, see
29 pytvdbapi Documentation, Release 0.5.0
30 Chapter 3. License CHAPTER 4
Credits
The following persons have in some way contributed to improving pytvdbapi and deserve a mention.
4.1 Contributors
• Alexander van Ratingen • Tobias Röttger • BenoitZugmeyer • Adam Whiteside
31 pytvdbapi Documentation, Release 0.5.0
32 Chapter 4. Credits CHAPTER 5
Contact
To get in contact with me personally you can send me an email at [email protected].
5.1 Feedback / Suggestions
To provide bug reports or feature requests, please use the project provided bug tracker, try to provide as much informa- tion as possible, including how to reproduce the issue, any log files produced and preferably a test case that highlights the issue. Or, feel free to implement the changes yourself and submit a pull request.
5.2 Twitter
You can follow me on Twitter @fuzzycode to get updates about pytvdbapi.
33 pytvdbapi Documentation, Release 0.5.0
34 Chapter 5. Contact Part IV
Indices and tables
35
pytvdbapi Documentation, Release 0.5.0
• genindex • modindex • search
37 pytvdbapi Documentation, Release 0.5.0
38 Python Module Index
p pytvdbapi.actor, 23 pytvdbapi.api, 15 pytvdbapi.banner, 24 pytvdbapi.error, 26
39 pytvdbapi Documentation, Release 0.5.0
40 Python Module Index Index
A P abbreviation (pytvdbapi.api.Language attribute), 16 pytvdbapi.actor (module), 23 Actor (class in pytvdbapi.actor), 23 pytvdbapi.api (module), 15 append() (pytvdbapi.api.Season method), 18 pytvdbapi.banner (module), 24 pytvdbapi.error (module), 26 B PytvdbapiError, 26 BadData, 26 Banner (class in pytvdbapi.banner), 24 S Search (class in pytvdbapi.api), 20 C search() (pytvdbapi.api.TVDB method), 20 ConnectionError, 26 Season (class in pytvdbapi.api), 18 Show (class in pytvdbapi.api), 16 E Episode (class in pytvdbapi.api), 19 T TVDB (class in pytvdbapi.api), 20 F TVDBAttributeError, 26 filter() (pytvdbapi.api.Season method), 18 TVDBIdError, 26 filter() (pytvdbapi.api.Show method), 17 TVDBIndexError, 26 find() (pytvdbapi.api.Season method), 19 TVDBNotFoundError, 26 find() (pytvdbapi.api.Show method), 17 TVDBValueError, 26 G U get_episode() (pytvdbapi.api.TVDB method), 22 update() (pytvdbapi.api.Show method), 18 get_episode_by_air_date() (pytvdbapi.api.TVDB method), 23 get_series() (pytvdbapi.api.TVDB method), 21 I image_url (pytvdbapi.actor.pytvdbapi.actor.Actor at- tribute), 24 L Language (class in pytvdbapi.api), 15 languages() (in module pytvdbapi.api), 16 load_actors() (pytvdbapi.api.Show method), 17 load_banners() (pytvdbapi.api.Show method), 18 N name (pytvdbapi.api.Language attribute), 16
41