tvdbclient

Command Line

When installed, tvdbclient is available as an executable named tvdb which offers three commands: - find - list - show

The tvdb command looks for a configuration file at:

~/.config/tvdb/tvdb.conf

The configuration file must contain a TVDB API-Key and can contain additional settings.

A minimal config file looks like this:

[tvdb]
api_key = my-api-key

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 --format option which currently allows to choose between tabular output (default) and JSON.

The --fields option controls which fields are included in the output. A field can be specified using the following syntax:

[LABEL@]NAME[:CONV]

Examples:

episode.name

The Episode name (with default label "Name")

Series@series.name

The Series name, labeled "Series"

Episode@episode.number:02d

Episode number, in two-digit format with label "Episode"

Some interesting field names:

• series.name

• series.date, series.year

• series.overview

• season.number

• season.date, season.year

• episode.name

• episode.number

• episode.date, episode.year

• episode.overview

Not all fields are available with all commands.

• the search command uses only the series.xxx fields.

• the list command uses all fields

• the fields available show command depend on whether a series, season or episode was requested.

Preferences for fields can be set in the config file.

Type tvdb [COMMAND] --help for more details.

Python API

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.