• Abstract and Figures
• Public Full-text

pytvdbapi Documentation Release 0.4.0 Björn Larsson November 22, 2013 Contents i ii pytvdbapi Documentation, Release 0.4.0 Welcome to the documentation for pytvdbapi version 0.4.0 Contents 1 pytvdbapi Documentation, Release 0.4.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 5 pytvdbapi Documentation, Release 0.4.0 It may work on other Python versions but they are not actively supported and tested against. 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]) <Show - Alarm für Cobra 11 - Die Autobahnpolizei> And: >>> result= db.search(u’Dexter’,’de’) >>> len(result) 3 >>> print(result[0]) <Show - Dexter> 1 http://docs.python.org/3.3/howto/unicode.html 6 Chapter 1. Basics pytvdbapi Documentation, Release 0.4.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.4.0 >>> print(show[2]) # Access a particular season <Season 002> 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]) <Episode - S002E003> 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 <Show - Dexter> 1.3.4 Working with an episode object Accessing episode attributes: 8 Chapter 1. Basics pytvdbapi Documentation, Release 0.4.0 >>> episode= show[2][4] >>> print(episode.EpisodeName) See-Through >>> hasattr(episode,’foo’) False >>> hasattr(episode,’Director’) True Access the containing season: >>> episode.season <Season 002> 1.3.5 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") >>> 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.6 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 1.3. Examples 9 pytvdbapi Documentation, Release 0.4.0 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() >>> len(show.actor_objects) 26 >>> len(show.banner_objects) 231 >>> print(show.actor_objects[0]) <Actor - Michael C. Hall> 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 >>> len(show.actor_objects) 26 >>> print(show.actor_objects[0]) <Actor - Michael C. Hall> >>> show.load_banners() # Load banners >>> len(show.banner_objects) 231 1.3.7 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: 10 Chapter 1. Basics pytvdbapi Documentation, Release 0.4.0 ... # 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.4.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 ... 15 pytvdbapi Documentation, Release 0.4.0 2.1.1 Languages class pytvdbapi.api.Language(abbrev, name, id) Bases: object Representing a language that is supported by the API.

Load more

  43

Copy Link