Television¶

Interfaces to all of the TV objects offered by the Trakt.tv API

trakt.tv.dismiss_recommendation(*args, **kwargs)¶: Dismiss the show matching the specified criteria from showing up in recommendations.

trakt.tv.get_recommended_shows(*args, **kwargs)¶: Get a list of TVShow’s recommended based on your watching history and your friends. Results are returned with the top recommendation first.

trakt.tv.genres(*args, **kwargs)¶: A list of all possible TVShow Genres

trakt.tv.popular_shows(*args, **kwargs)¶

trakt.tv.trending_shows(*args, **kwargs)¶: All TVShow’s being watched right now

trakt.tv.updated_shows(*args, **kwargs)¶: All TVShow’s updated since timestamp (PST). To establish a baseline timestamp, you can use the server/time method. It’s recommended to store the timestamp so you can be efficient in using this method.

class trakt.tv.TVShow(title='', slug=None, **kwargs)¶

A Class representing a TV Show object

add_to_collection()¶: Add this TVShow to your library.

add_to_library()¶: Add this TVShow to your library.

add_to_watchlist()¶: Add this TVShow to your watchlist

aliases¶: A list of Alias objects representing all of the other titles that this TVShow is known by, and the countries where they go by their alternate titles

cast¶: All of the cast members that worked on this TVShow

comment(comment_body, spoiler=False, review=False)¶: Add a comment (shout or review) to this Move on trakt.

comments¶: All comments (shouts and reviews) for this TVShow. Most recent comments returned first.

crew¶: All of the crew members that worked on this TVShow

dismiss()¶: Dismiss this movie from showing up in Movie Recommendations

ext¶

ext_full¶

get_translations(**kwargs)¶

Returns all Translation’s for a movie, including language and translated values for title, tagline and overview.

Parameters:	country_code – The 2 character country code to search from
Returns:	a `list` of `Translation` objects

ids¶: Accessor to the trakt, imdb, and tmdb ids, as well as the trakt.tv slug

images¶: All of the artwork associated with this TVShow

images_ext¶: Uri to retrieve additional image information

mark_as_seen(watched_at=None)¶: Add this TVShow, watched outside of trakt, to your library.

mark_as_unseen()¶: Remove this TVShow, watched outside of trakt, from your library.

people¶: A list of all of the People involved in this TVShow, including both cast and crew

rate(rating)¶: Rate this TVShow on trakt. Depending on the current users settings, this may also send out social updates to facebook, twitter, tumblr, and path.

ratings¶: Ratings (between 0 and 10) and distribution for a movie.

related¶: The top 10 TVShow’s related to this TVShow

remove_from_collection()¶: Remove this TVShow from your library.

remove_from_library()¶: Remove this TVShow from your library.

remove_from_watchlist()¶

classmethod search(title, year=None)¶

Perform a search for the specified title

Parameters:	title – The title to search for

seasons¶: A list of TVSeason objects representing all of this show’s seasons

to_json()¶

watching_now¶: A list of all User’s watching a movie.

class trakt.tv.TVEpisode(show, season, number=-1, **kwargs)¶

Container for TV Episodes

add_to_collection()¶: Add this TVEpisode to your Trakt.tv library

add_to_library()¶: Add this TVEpisode to your Trakt.tv library

add_to_watchlist()¶: Add this TVEpisode to your watchlist

comment(comment_body, spoiler=False, review=False)¶: Add a comment (shout or review) to this TVEpisode on trakt.

comments¶: All comments (shouts and reviews) for this TVEpisode. Most recent comments returned first.

ext¶

ext_full¶

first_aired_date¶: Python datetime object representation of the first_aired date of this TVEpisode

get_description()¶: backwards compatible function that returns this TVEpisode’s overview ‘

ids¶: Accessor to the trakt, imdb, and tmdb ids, as well as the trakt.tv slug

images¶: All of the artwork associated with this TVEpisode

images_ext¶: Uri to retrieve additional image information

mark_as_seen(watched_at=None)¶: Mark this episode as seen

mark_as_unseen()¶: Remove this TVEpisode from your list of watched episodes

rate(rating)¶: Rate this TVEpisode on trakt. Depending on the current users settings, this may also send out social updates to facebook, twitter, tumblr, and path.

ratings¶: Ratings (between 0 and 10) and distribution for a movie.

remove_from_collection()¶: Remove this TVEpisode from your library

remove_from_library()¶: Remove this TVEpisode from your library

remove_from_watchlist()¶: Remove this TVEpisode from your watchlist

scrobble(progress, app_version, app_date)¶

Scrobble this TVEpisode via the TraktTV Api

Parameters:

progress – % progress, integer 0-100. It is recommended to call the watching API every 15 minutes, then call the scrobble API near the end of the movie to lock it in.
app_version – Version number of the media center, be as specific as you can including nightly build number, etc. Used to help debug your plugin.
app_date – Build date of the media center. Used to help debug your plugin.

classmethod search(title, year=None)¶

Perform a search for an episode with a title matching title

Parameters:	title – The title to search for year – Optional year to limit results to

to_json()¶: Return this TVEpisode as a trakt recognizable JSON object

watching_now¶: A list of all User’s watching a movie.

class trakt.tv.TVSeason(show, season=1, slug=None, **kwargs)¶

Container for TV Seasons

add_to_collection()¶: Add this TVSeason to your library.

add_to_library()¶: Add this TVSeason to your library.

comments¶: All comments (shouts and reviews) for this TVSeason. Most recent comments returned first.

episodes¶: A list of TVEpisode objects representing all of the Episodes in this TVSeason. Because there is no “Get all episodes for a season” endpoint on the trakt api

ratings¶: Ratings (between 0 and 10) and distribution for a movie.

remove_from_collection()¶: Remove this TVSeason from your library.

remove_from_library()¶: Remove this TVSeason from your library.

to_json()¶: Return this TVSeason as a Trakt consumable API blob

watching_now¶: A list of all User’s watching a movie.

class trakt.tv.Translation(title, overview, language)¶

language¶: Alias for field number 2

overview¶: Alias for field number 1

title¶: Alias for field number 0

Example Usage¶

The trakt.tv module has interfaces to all of the TV resources mentioned above and is almost a direct port of the trakt.movies module. It has the same interfaces to dismiss shows from recommendations, getting recommendations, rating a list of shows, rating a list of episodes, getting a list of valid show genres, a list of trending shows, and getting a list of recently updated shows and dealing with specific shows, seasons, and episodes.

For our first example let’s start by grabbing a specific show

>>> from trakt.tv import TVShow
>>> it_crowd = TVShow('The IT Crowd')

Well that was pretty painless. Ok, now let’s pull some data out of our it_crowd object

>>> it_crowd.people
[<Person>: Chris O'Dowd, <Person>: Katherine Parkinson, <Person>: None,
<Person>: Richard Ayoade, <Person>: Chris Morris, <Person>: Matt Berry, <Person>: Noel Fielding]
>>> it_crowd.top_episodes
[<TVEpisode>: The IT Crowd S1E1 Yesterday's Jam, <TVEpisode>: The IT Crowd S1E2 Calamity Jen,
 <TVEpisode>: The IT Crowd S2E1 The Work Outing, <TVEpisode>: The IT Crowd S1E4 The Red Door,...
>>> it_crowd.top_watchers
[<User>: b'Vaelek', <User>: b'Governa', <User>: b'shanos404', <User>: b'b_jammin666',
<User>: b'pavvoc', <User>: b'heartbraden', <User>: b'tressal', <User>: b'hherrera',...
>>> it_crowd.genres
[Genre(name='Comedy', slug='comedy')]

Now that we’ve gotten some information on the show, let’s start doing something interesting and interacting with the API via the TVShow’s methods

>>> it_crowd.add_to_library()
>>> it_crowd.comment('Wow, I REALLY love this show')
>>> it_crowd.comment('They should never have given Jen the internet.',
                     spoiler=True, review=True)

Now that we’ve gotten some information on the show, let’s dive down and get some information on the show’s seasons and episodes

>>> s1 = it_crowd.seasons[1]
>>> s1.episodes
[<TVEpisode>: The IT Crowd S1E-1 Yesterday's Jam, <TVEpisode>: The IT Crowd S1E-1 Calamity Jen,
<TVEpisode>: The IT Crowd S1E-1 Fifty-Fifty, <TVEpisode>: The IT Crowd S1E-1 The Red Door,
<TVEpisode>: The IT Crowd S1E-1 The Haunting of Bill Crouse, <TVEpisode>: The IT Crowd S1E-1 Aunt Irma Visits]
>>> pilot = s1.episodes[0]
>>> pilot.title
'Yesterday's Jam'
>>> pilot.overview
'Jen is hired as the manager Reynholm Industries although she doesn't know the first thing about computers.'