A Python library and command line client for the TVDB API.
Download tvdbclient version 0.2.4
tvdbclient is a client library for the for webservice API provided by the TVDB (http://tvdb.com). It can be used as a library in other Python projects or as a standalone command line application.
Examples for command line and API usage.
When installed, tvdbclient is available as an executable named
which offers three commands:
tvdb command looks for a configuration file at:
The configuration file must contain a TVDB API-Key and can contain additional settings.
A minimal config file looks like this:
The find command is used to query TVDB using a singled search string:
$ tvdb find sopranos ID Name Year Language ============== ============================ ============ ==================== 75299 The Sopranos 1999 en
The list command lists episodes for a given series:
$ tvdb list sopranos 2 Series Season Episode Name Year ============= ======== ========= =================================== ======= The Sopranos 02 01 Guy Walks Into a Psychiatrist's 2000 Office The Sopranos 02 02 Do Not Resuscitate 2000 The Sopranos 02 03 Toodle-Fucking-Oo 2000 The Sopranos 02 04 Commendatori 2000 The Sopranos 02 05 Big Girls Don't Cry 2000 The Sopranos 02 06 The Happy Wanderer 2000 The Sopranos 02 07 D-Girl 2000 The Sopranos 02 08 Full Leather Jacket 2000 The Sopranos 02 09 From Where to Eternity 2000 The Sopranos 02 10 Bust Out 2000 The Sopranos 02 11 House Arrest 2000 The Sopranos 02 12 Knight in White Satin Armor 2000 The Sopranos 02 13 Funhouse 2000
You can leave out the second parameter to list episodes for all seasons.
The show command displays details for a single entity, which can be either a Series, an Season or an Episode, depending on how specific the command is given:
$ tvdb show sopranos 2 2 Series: The Sopranos Season: 2 Episode: 2 Name: Do Not Resuscitate Date: 2000-01-23 Overview: Tony plays both ends against the middle in a construction dispute, while Pussy has a revealing meeting with an FBI agent. Livia becomes suspicious of Janice as she starts to get cozy. Junior is released from jail, but finds himself working on a tight leash under Tony's thumb. ID: 167553
The last parameter is the episode number. Leaving it out will display details for the Season (which are admittedly not many). Leaving out the second parameter as well displays information on the Series.
The output of all commands can be controlled with the
which currently allows to choose between tabular output (default) and JSON.
--fields option controls which fields are included in the output.
A field can be specified using the following syntax:
The Episode name (with default label "Name")
The Series name, labeled "Series"
Episode number, in two-digit format with label "Episode"
Some interesting field names:
Not all fields are available with all commands.
searchcommand uses only the
listcommand uses all fields
the fields available
showcommand depend on whether a series, season or episode was requested.
fields can be set in the config file.
tvdb [COMMAND] --help for more details.
To use tvdbclient in a project:
import tvdbclient api_key = 'my-api-key' tvdb = tvdbclient.TVDB(api_key) # searching results = tvdb.search('sopranos') for series in results: print(series.name) print(series.year) # series details series = tvdb.series(75299) print(series.name) print(series.overview) for season in series.seasons: for episode in season: print(episode.name) print(episode.number)
The series details and episode are not provided by TVDB search results.
If you access for example the episode list of a series that was obtained
from a search,
tvdbclient has to fetch the series details first:
import tvdbclient tvdb = tvdbclient.TVDB('my-api-key') for series in tvdb.search('galactica'): for episode in series.iter_episodes(): # fetches details print(episode.name)
Details are loaded transparently, but a request to the webservice is made for each series.