pytvdbapi Documentation Release 0.5.0 Björn Larsson December 28, 2015 Contents I Basics 3 1 Basics 5 1.1 Getting Started..............................................5 1.2 Python 2.X and 3.X...........................................6 1.3 Examples.................................................7 II Modules 13 2 pytvdbapi modules 15 2.1 api Module............................................... 15 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 5 Contact 33 5.1 Feedback / Suggestions......................................... 33 5.2 Twitter.................................................. 33 IV Indices and tables 35 Python Module Index 39 i 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]) <Show - Alarm für Cobra 11 - Die Autobahnpolizei> And: >>> result= db.search(u'Dexter','de') >>> len(result) 3 >>> print(result[0]) <Show - Dexter> 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 <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.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 <Season 002> 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]) <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 >>> assert len(show.actor_objects)>0 10 Chapter 1. Basics pytvdbapi Documentation, Release 0.5.0 >>> print(show.actor_objects[0]) <Actor - Michael C. Hall> >>> 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