Television¶

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

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

checkin(app_version, app_date, message='', sharing=None, venue_id='', venue_name='', delete=False)¶

Checkin this TVEpisode via the TraktTV API

:param 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.

Parameters:

app_date – Build date of the media center. Used to help debug your plugin.
message – Message used for sharing. If not sent, it will use the watching string in the user settings.
sharing – Control sharing to any connected social networks.
venue_id – Foursquare venue ID.
venue_name – Foursquare venue name.

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

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

end_time_from_custom_start(start_date=None)¶

Calculate a python datetime object representing the calculated end time of an episode from the given start_date. ie, start_date + runtime.

Parameters:: start_date – a datetime instance indicating the start date of a

given airing of this episode. Defaults to the first_aired_date of this episode.

property ext¶

property ext_full¶

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

property first_aired_end_time¶: Python datetime object representing the corresponding end time of the first_aired date of this episode

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

property images¶: All of the artwork associated with this TVEpisode

property 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, rated_at=None)¶: Rate this TVEpisode on trakt. Depending on the current users settings, this may also send out social updates to facebook, twitter, tumblr, and path.

property 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.

static 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

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

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

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

Container for TV Seasons

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

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

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

property 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

property 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

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

class trakt.tv.TVShow(title='', slug=None, seasons=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

property 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

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

collection_progress(**kwargs)¶

collection progress for a show including details on all aired seasons and episodes.

The next_episode will be the next episode the user should collect, if there are no upcoming episodes it will be set to null.

specials: include specials as season 0. Default: false. count_specials: count specials in the overall stats. Default: false. hidden: include any hidden seasons. Default: false.

https://trakt.docs.apiary.io/#reference/shows/collection-progress/get-show-collection-progress

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

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

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

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

property ext¶

property ext_full¶

get_translations(country_code='us')¶

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

property images¶: All of the artwork associated with this TVShow

property images_ext¶: Uri to retrieve additional image information.

property last_episode¶: Returns the most recently aired TVEpisode. If no episode is found, None will be returned.

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.

property next_episode¶: Returns the next scheduled to air TVEpisode. If no episode is found, None will be returned.

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

property progress¶

collection progress for a show including details on all aired seasons and episodes.

The next_episode will be the next episode the user should collect, if there are no upcoming episodes it will be set to null.

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

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

property 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()¶

static search(title, year=None)¶

Perform a search for the specified title.

Parameters:

title – The title to search for
year – An optional year for the item you’re searching for.

property seasons¶: A list of TVSeason objects representing all of this show’s seasons which each contain TVEpisode elements

property slug¶

to_json()¶

to_json_singular()¶

watched_progress(**kwargs)¶

watched progress for a show including details on all aired seasons and episodes.

specials: include specials as season 0. Default: false. count_specials: count specials in the overall stats. Default: false. hidden: include any hidden seasons. Default: false.

https://trakt.docs.apiary.io/#reference/shows/watched-progress/get-show-collection-progress

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

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

language: str¶: Alias for field number 2

overview: str¶: Alias for field number 1

title: str¶: Alias for field number 0

trakt.tv.anticipated_shows(page=1, limit=10, extended=None)¶

Return most anticipated shows based on the number of lists: a show appears on.

trakt.tv.collected_shows(time_period='weekly', page=1, limit=10, extended=None)¶

Return most collected (unique users) shows in the specified time period.

Defaulting to weekly. All stats are relative to the specific time period.

trakt.tv.dismiss_recommendation(title=None)¶: Dismiss the show matching the specified criteria from showing up in recommendations.

trakt.tv.genres()¶: A list of all possible TVShow Genres

trakt.tv.get_recommended_shows(page=1, limit=10)¶: 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.played_shows(time_period='weekly', page=1, limit=10, extended=None)¶: the most played shows. (a single user can watch multiple episodes multiple times)

shows in the specified time period, defaulting to weekly. All stats are relative to the specific time period.

trakt.tv.popular_shows(page=1, limit=10, extended=None)¶

trakt.tv.recommended_shows(time_period='weekly', page=1, limit=10, extended=None)¶

The most recommended shows in the specified time period,: defaulting to weekly.

All stats are relative to the specific time period.

trakt.tv.trending_shows(page=1, limit=10, extended=None)¶: All TVShow’s being watched right now

trakt.tv.updated_shows(timestamp=None, page=1, limit=10, extended=None)¶: 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.

trakt.tv.watched_shows(time_period='weekly', page=1, limit=10, extended=None)¶

Return most watched (unique users) shows in the specified time period.

Defaulting to weekly. All stats are relative to the specific time period.

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>: 'Vaelek', <User>: 'Governa', <User>: 'shanos404', <User>: 'b_jammin666',
<User>: 'pavvoc', <User>: 'heartbraden', <User>: 'tressal', <User>: '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.'

Television¶

Example Usage¶

Table of Contents

Previous topic

Next topic