Series¶

As on the IMDb site, each TV series and also each of a TV series’ episodes is treated as a regular title, just like a movie. The kind key can be used to distinguish series and episodes from movies:

>>> series = ia.get_movie('0389564')
>>> series
<Movie id:0389564[http] title:_"The 4400" (2004)_>
>>> series['kind']
'tv series'
>>> episode = ia.get_movie('0502803')
>>> episode
<Movie id:0502803[http] title:_"The 4400" Pilot (2004)_>
>>> episode['kind']
'episode'

The episodes of a series can be fetched using the “episodes” infoset. This infoset adds an episodes key which is a dictionary from season numbers to episodes. And each season is a dictionary from episode numbers within the season to the episodes. Note that the season and episode numbers don’t start from 0; they are the numbers given by the IMDb:

>>> ia.update(series, 'episodes')
>>> sorted(series['episodes'].keys())
[1, 2, 3, 4]
>>> season4 = series['episodes'][4]
>>> len(season4)
13
>>> episode = series['episodes'][4][2]
>>> episode
<Movie id:1038701[http] title:_"The 4400" Fear Itself (2007)_>
>>> episode['season']
4
>>> episode['episode']
2

The title of the episode doesn’t contain the title of the series:

>>> episode['title']
'Fear Itself'
>>> episode['series title']
'The 4400'

The episode also contains a key that refers to the series, but beware that, to avoid circular references, it’s not the same object as the series object we started with:

>>> episode['episode of']
<Movie id:0389564[http] title:_"The 4400" (None)_>
>>> series
<Movie id:0389564[http] title:_"The 4400" (2004)_>

Titles¶

The analyze_title() and build_title() functions now support TV episodes. You can pass a string to the analyze_title function in the format used by the web server ("The Series" The Episode (2005)) or in the format of the plain text data files ("The Series" (2004) {The Episode (#ser.epi)}).

For example, if you call the function:

analyze_title('"The Series" The Episode (2005)')

the result will be:

{
    'kind': 'episode',        # kind is set to 'episode'
    'year': '2005',           # release year of this episode
    'title': 'The Episode',   # episode title
    'episode of': {           # 'episode of' will contain
        'kind': 'tv series',  # information about the series
        'title': 'The Series'
    }
}

The episode of key can be a dictionary or a Movie instance with the same information.

The build_title() function takes an optional argument: ptdf, which when set to false (the default) returns the title of the episode in the format used by the IMDb’s web server (“The Series” An Episode (2006)); otherwise, it uses the format used by the plain text data files (something like “The Series” (2004) {An Episode (#2.5)})

Full credits¶

When retrieving credits for a TV series or mini-series, you may notice that many long lists (like “cast” and “writers”) are incomplete. You can fetch the complete list of cast and crew with the “full credits” data set:

>>> series = ia.get_movie('0285331')
>>> series
<Movie id:0285331[http] title:_"24" (2001)_>
>>> len(series['cast'])
50
>>> ia.update(series, 'full credits')
>>> len(series['cast'])
2514

Ratings¶

You can retrieve rating information about every episode in a TV series or mini series using the ‘episodes rating’ data set.

People¶

You can retrieve information about single episodes acted/directed/… by a person.

from imdb import Cinemagoer
i = Cinemagoer()
p = i.get_person('0005041')  # Laura Innes
p['filmography']['actress'][0]   # <Movie id:0568152[http] title:_"ER" (????)_>

# At this point you have an entry (in keys like 'actor', 'actress',
# 'director', ...) for every series the person starred/worked in, but
# you knows nothing about singles episodes.
i.update(p, 'episodes')  # updates information about single episodes.

p['episodes']    # a dictionary with the format:
                 #    {<TV Series Movie Object>: [
                 #                                <Episode Movie Object>,
                 #                                <Episode Movie Object>,
                 #                                ...
                 #                               ],
                 #     ...
                 #    }

er = p['actress'][0]  # ER tv series
p['episodes'][er]     # list of Movie objects; one for every ER episode
                      # she starred/worked in

p['episodes'][er][0]  # <Movie id:0568154[http] title:_"ER" Welcome Back Carter! (1995)_>
p['episodes'][er]['kind']   # 'episode'
p['episodes'][er][0].currentRole   # 'Dr. Kerry Weaver'

Goodies¶

In the imdb.helpers module there are some functions useful to manage lists of episodes:

sortedSeasons(m) returns a sorted list of seasons of the given series, e.g.:

>>> from imdb import Cinemagoer
>>> i = Cinemagoer()
>>> m = i.get_movie('0411008')
>>> i.update(m, 'episodes')
>>> sortedSeasons(m)
[1, 2]

sortedEpisodes(m, season=None) returns a sorted list of episodes of the the given series for only the specified season(s) (if None, every season), e.g.:

>>> from imdb import Cinemagoer
>>> i = Cinemagoer()
>>> m = i.get_movie('0411008')
>>> i.update(m, 'episodes')
>>> sortedEpisodes(m, season=1)
[<Movie id:0636289[http] title:_"Lost" Pilot: Part 1 (2004)_>, <Movie id:0636290[http] title:_"Lost" Pilot: Part 2 (2004)_>, ...]