tvdbsimple.series module
This module implements the Series functionality of TheTVDb API. Allows to retrieve series info, actors, basic episodes info and images.
# -*- coding: utf-8 -*-
"""
This module implements the Series functionality of TheTVDb API.
Allows to retrieve series info, actors, basic episodes info and images.
See [Series API section](https://api.thetvdb.com/swagger#/Series)
"""
from .base import TVDB
class Series(TVDB):
"""
Series class to retrieve all the info about a series.
Requires the series id.
"""
_BASE_PATH = 'series'
_URLS = {
'info': '/{id}',
'actors': '/{id}/actors'
}
def __init__(self, id, language=''):
"""
Initialize the series class.
`id` is the TheTVDb series id. You can also provide `language`,
the language id you want to use to retrieve the info.
"""
self._set_language(language)
self.Images = Series_Images(id, language)
"""
Allows to retrieve images info.
"""
self.Episodes = Series_Episodes(id, language)
"""
Allows to retrieve episodes info.
"""
super(Series, self).__init__(id)
def info(self, language=''):
"""
Get the basic show information for a specific show id and sets
them to the attributes.
You also provide `language`, the language id you want to use
to retrieve the info.
Returns a dict with the series info
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> show = tvdb.Series(78804)
>>> response = show.info()
>>> show.seriesName
'Doctor Who (2005)'
"""
path = self._get_id_path('info')
self._set_language(language)
response = self._GET(path)
self._set_attrs_to_values(response)
return response
def actors(self, language=''):
"""
Get the actors for the show id and sets them to
`actors` the attributes.
You also provide `language`, the language id you want to use
to retrieve the info.
Returns a list of actors with their info.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> show = tvdb.Series(78804)
>>> response = show.actors()
>>> show.actors[0]['name']
u'David Tennant'
"""
path = self._get_id_path('actors')
self._set_language(language)
response = self._GET(path)
self._set_attrs_to_values({'actors': response})
return response
class Series_Episodes(TVDB):
"""
Class needed to organize series episodes. Allow to retrieve basic
info episodes for the series.
Requires the series id.
"""
_BASE_PATH = 'series'
_URLS = {
'summary': '/{id}/episodes/summary',
'episodes': '/{id}/episodes',
'query': '/{id}/episodes/query',
'queryparams': '/{id}/episodes/query/params'
}
def __init__(self, id, language='', **kwargs):
"""
Initialize the class.
`id` is the TheTVDb series id.
You can provide `language`, the language id you want to use to
retrieve the info.
You can provide `absoluteNumber` to get only episodes with the
provided absolute number.
You can provide `airedSeason` to get only episodes with the
provided aired season number.
You can provide `airedEpisode` to get only episodes with the
provided aired episode number.
You can provide `dvdSeason` to get only episodes with the
provided dvd season number.
You can provide `dvdEpisode` to get only episodes with the
provided dvd episode number.
You can provide `imdbId` to get only episodes with the
provided imdb id.
"""
super(Series_Episodes, self).__init__(id)
self._set_language(language)
self.update_filters(**kwargs)
def update_filters(self, **kwargs):
"""
Set the filters for the episodes of the specific show id.
You can provide `absoluteNumber` to get only episodes with the
provided absolute number.
You can provide `airedSeason` to get only episodes with the
provided aired season number.
You can provide `airedEpisode` to get only episodes with the
provided aired episode number.
You can provide `dvdSeason` to get only episodes with the
provided dvd season number.
You can provide `dvdEpisode` to get only episodes with the
provided dvd episode number.
You can provide `imdbId` to get only episodes with the
provided imdb id.
"""
self._PAGES = -1
self._PAGES_LIST = {}
self._FILTERS=kwargs
def summary(self):
"""
Get the episodes summary for a specific show id and sets
them to their attributes.
Returns a dict with a summary of the episodes.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showeps = tvdb.Series_Episodes(78804)
>>> response = showeps.summary()
>>> showeps.airedEpisodes
'267'
"""
path = self._get_id_path('summary')
response = self._GET(path)
self._set_attrs_to_values(response)
return response
def query_params(self):
"""
Get the query parameters allowed for a specific show id.
Returns a dict with all the filters allowed.
"""
path = self._get_id_path('query_params')
response = self._GET(path)
self._set_attrs_to_values({'query_params': response})
return response
def pages(self):
"""
Get the number of episode pages for filtered episodes of a specific show id.
Returns the integer number of pages for filtered episodes of the show.
"""
if self._PAGES < 0:
self.page(1)
return self._PAGES
def all(self):
"""
Get the full episode list with basic details for a specific show id.
Returns a list of episodes with basic info.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showeps = tvdb.Series_Episodes(78804)
>>> response = showeps.all()
>>> showeps.episodes[0]['episodeName']
'Rose'
"""
episodes = []
for i in range (1, self.pages()+1):
episodes.extend(self.page(i))
self._set_attrs_to_values({'episodes': episodes})
return episodes
def page(self, page):
"""
Get the episode list for a specific page of a show id.
`page` is the page number of the episodes list to retrieve
Returns a list episodes with basic info.
"""
if page in self._PAGES_LIST:
return self._PAGES_LIST[page]
if self._FILTERS:
path = self._get_id_path('query')
else:
path = self._get_id_path('episodes')
filters = self._FILTERS.copy()
filters['page'] = page
response = self._GET(path, params=filters, cleanJson=False)
if 'links' in response and 'last' in response['links']:
self._PAGES = response['links']['last']
self._PAGES_LIST[page] = response['data']
return response['data']
def __iter__(self):
for i in range (1, self.pages()+1):
yield self.page(i)
class Series_Images(TVDB):
"""
Class needed to organize series images. Allow to retrieve all
the types of images of a series.
Requires the series id.
language: (optional) language to request.
resolution: (optional) image resolution.
subKey: (optional) subkey research.
"""
_BASE_PATH = 'series'
_URLS = {
'imagequery': '/{id}/images/query',
'summary': '/{id}/images',
'queryparams': '/{id}/images/query/params'
}
def __init__(self, id, language='', **kwargs):
"""
Initialize the class.
`id` is the TheTVDb series id.
You can provide `language`, the language id you want to use to
retrieve the info.
You can provide `reqolution` to get only episodes with the
provided resolution.
You can provide `subKey` to get only episodes with the
provided subKey.
"""
super(Series_Images, self).__init__(id)
self._set_language(language)
self.update_filters(**kwargs)
def update_filters(self, **kwargs):
"""
Set the filters for the episodes of the specific show id.
You can provide `language`, the language id you want to use to
retrieve the info.
You can provide `reqolution` to get only episodes with the
provided resolution.
You can provide `subKey` to get only episodes with the
provided subKey.
"""
self._FILTERS=kwargs
def summary(self):
"""
Get the images summary for a specific show id and sets
them to `summary` attributes.
Returns a dict with a summary of the images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.summary()
>>> showimgs.summary['poster']
53
"""
path = self._get_id_path('summary')
response = self._GET(path)
self._set_attrs_to_values(response)
return response
def query_params(self):
"""
Get the query parameters allowed for a specific show id.
Returns:
A dict respresentation of the JSON returned from the API.
"""
path = self._get_id_path('query_params')
response = self._GET(path)
self._set_attrs_to_values({'query_params': response})
return response
def poster(self, language=''):
"""
Get the posters for a specific show.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of posters.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.poster()
>>> showimgs.poster[0]['resolution']
'680x1000'
"""
return self._get_image_type('poster', language)
def fanart(self, language=''):
"""
Get the fanarts for a specific show.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of fanarts.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.fanart()
>>> showimgs.fanart[0]['resolution']
'1280x720'
"""
return self._get_image_type('fanart', language)
def series(self, language=''):
"""
Get the series images for a specific show.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of series images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.series()
>>> showimgs.series[0]['thumbnail']
'_cache/text/34391.jpg'
"""
return self._get_image_type('series', language)
def season(self, language=''):
"""
Get the season images for a specific show.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of season images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.season()
>>> showimgs.season[0]['thumbnail']
'_cache/seasons/34391-1.jpg'
"""
return self._get_image_type('season', language)
def seasonwide(self, language=''):
"""
Get the seasonwide images for a specific show.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of seasonwide images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.seasonwide()
>>> showimgs.seasonwide[0]['thumbnail']
'_cache/seasonswide/78804-1.jpg'
"""
return self._get_image_type('seasonwide', language)
def all(self, language=''):
"""
Get all the images for a specific show and sets it to `images` attribute.
It needs to have at least one filter set.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804, resolution='1280x720')
>>> response = showimgs.all()
>>> showimgs.images[0]['resolution']
'1280x720'
"""
return self._get_image_type('images', language)
def _get_image_type(self, type, language=''):
path = self._get_id_path('imagequery')
self._set_language(language)
filters = self._FILTERS.copy()
if type != 'images':
filters['keyType'] = type
response = self._GET(path, params=filters)
self._set_attrs_to_values({type: response})
return response
Classes
class Series
Series class to retrieve all the info about a series. Requires the series id.
class Series(TVDB):
"""
Series class to retrieve all the info about a series.
Requires the series id.
"""
_BASE_PATH = 'series'
_URLS = {
'info': '/{id}',
'actors': '/{id}/actors'
}
def __init__(self, id, language=''):
"""
Initialize the series class.
`id` is the TheTVDb series id. You can also provide `language`,
the language id you want to use to retrieve the info.
"""
self._set_language(language)
self.Images = Series_Images(id, language)
"""
Allows to retrieve images info.
"""
self.Episodes = Series_Episodes(id, language)
"""
Allows to retrieve episodes info.
"""
super(Series, self).__init__(id)
def info(self, language=''):
"""
Get the basic show information for a specific show id and sets
them to the attributes.
You also provide `language`, the language id you want to use
to retrieve the info.
Returns a dict with the series info
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> show = tvdb.Series(78804)
>>> response = show.info()
>>> show.seriesName
'Doctor Who (2005)'
"""
path = self._get_id_path('info')
self._set_language(language)
response = self._GET(path)
self._set_attrs_to_values(response)
return response
def actors(self, language=''):
"""
Get the actors for the show id and sets them to
`actors` the attributes.
You also provide `language`, the language id you want to use
to retrieve the info.
Returns a list of actors with their info.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> show = tvdb.Series(78804)
>>> response = show.actors()
>>> show.actors[0]['name']
u'David Tennant'
"""
path = self._get_id_path('actors')
self._set_language(language)
response = self._GET(path)
self._set_attrs_to_values({'actors': response})
return response
Ancestors (in MRO)
- Series
- tvdbsimple.base.TVDB
- builtins.object
Static methods
def __init__(
self, id, language='')
Initialize the series class.
id
is the TheTVDb series id. You can also provide language
,
the language id you want to use to retrieve the info.
def __init__(self, id, language=''):
"""
Initialize the series class.
`id` is the TheTVDb series id. You can also provide `language`,
the language id you want to use to retrieve the info.
"""
self._set_language(language)
self.Images = Series_Images(id, language)
"""
Allows to retrieve images info.
"""
self.Episodes = Series_Episodes(id, language)
"""
Allows to retrieve episodes info.
"""
super(Series, self).__init__(id)
def actors(
self, language='')
Get the actors for the show id and sets them to
actors
the attributes.
You also provide language
, the language id you want to use
to retrieve the info.
Returns a list of actors with their info.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> show = tvdb.Series(78804)
>>> response = show.actors()
>>> show.actors[0]['name']
u'David Tennant'
def actors(self, language=''):
"""
Get the actors for the show id and sets them to
`actors` the attributes.
You also provide `language`, the language id you want to use
to retrieve the info.
Returns a list of actors with their info.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> show = tvdb.Series(78804)
>>> response = show.actors()
>>> show.actors[0]['name']
u'David Tennant'
"""
path = self._get_id_path('actors')
self._set_language(language)
response = self._GET(path)
self._set_attrs_to_values({'actors': response})
return response
def get_token(
self, forceNew=False)
Get the existing token or creates it if it doesn't exist. Returns the API token.
If forceNew
is true the function will do a new login to retrieve the token.
def get_token(self, forceNew=False):
"""
Get the existing token or creates it if it doesn't exist.
Returns the API token.
If `forceNew` is true the function will do a new login to retrieve the token.
"""
from . import KEYS
if not KEYS.API_TOKEN or forceNew:
if not KEYS.API_KEY:
raise APIKeyError
if hasattr(self,"USER") and hasattr(self,"USER_KEY"):
data = {"apikey": KEYS.API_KEY, "username": self.USER, "userkey": self.USER_KEY}
else:
data={"apikey": KEYS.API_KEY}
response = requests.request(
'POST', self._get_complete_url('login'),
data=json.dumps(data),
headers=self._headers)
if response.status_code == 200:
KEYS.API_TOKEN = response.json()['token']
else:
error = "Unknown error while authenticating. Check your api key or your user/userkey"
try:
error = response.json()['error']
except:
pass
raise AuthenticationError(error)
return KEYS.API_TOKEN
def info(
self, language='')
Get the basic show information for a specific show id and sets them to the attributes.
You also provide language
, the language id you want to use
to retrieve the info.
Returns a dict with the series info
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> show = tvdb.Series(78804)
>>> response = show.info()
>>> show.seriesName
'Doctor Who (2005)'
def info(self, language=''):
"""
Get the basic show information for a specific show id and sets
them to the attributes.
You also provide `language`, the language id you want to use
to retrieve the info.
Returns a dict with the series info
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> show = tvdb.Series(78804)
>>> response = show.info()
>>> show.seriesName
'Doctor Who (2005)'
"""
path = self._get_id_path('info')
self._set_language(language)
response = self._GET(path)
self._set_attrs_to_values(response)
return response
def refresh_token(
self)
Refresh the current token set in the module.
Returns the new obtained valid token for the API.
def refresh_token(self):
"""
Refresh the current token set in the module.
Returns the new obtained valid token for the API.
"""
self._set_token_header()
response = requests.request(
'GET', self._get_complete_url('refresh_token'),
headers=self._headers)
response.raise_for_status()
jsn = response.json()
if 'token' in jsn:
from . import KEYS
KEYS.API_TOKEN = jsn['token']
return KEYS.API_TOKEN
return ''
Instance variables
var Episodes
Allows to retrieve episodes info.
var Images
Allows to retrieve images info.
class Series_Episodes
Class needed to organize series episodes. Allow to retrieve basic info episodes for the series. Requires the series id.
class Series_Episodes(TVDB):
"""
Class needed to organize series episodes. Allow to retrieve basic
info episodes for the series.
Requires the series id.
"""
_BASE_PATH = 'series'
_URLS = {
'summary': '/{id}/episodes/summary',
'episodes': '/{id}/episodes',
'query': '/{id}/episodes/query',
'queryparams': '/{id}/episodes/query/params'
}
def __init__(self, id, language='', **kwargs):
"""
Initialize the class.
`id` is the TheTVDb series id.
You can provide `language`, the language id you want to use to
retrieve the info.
You can provide `absoluteNumber` to get only episodes with the
provided absolute number.
You can provide `airedSeason` to get only episodes with the
provided aired season number.
You can provide `airedEpisode` to get only episodes with the
provided aired episode number.
You can provide `dvdSeason` to get only episodes with the
provided dvd season number.
You can provide `dvdEpisode` to get only episodes with the
provided dvd episode number.
You can provide `imdbId` to get only episodes with the
provided imdb id.
"""
super(Series_Episodes, self).__init__(id)
self._set_language(language)
self.update_filters(**kwargs)
def update_filters(self, **kwargs):
"""
Set the filters for the episodes of the specific show id.
You can provide `absoluteNumber` to get only episodes with the
provided absolute number.
You can provide `airedSeason` to get only episodes with the
provided aired season number.
You can provide `airedEpisode` to get only episodes with the
provided aired episode number.
You can provide `dvdSeason` to get only episodes with the
provided dvd season number.
You can provide `dvdEpisode` to get only episodes with the
provided dvd episode number.
You can provide `imdbId` to get only episodes with the
provided imdb id.
"""
self._PAGES = -1
self._PAGES_LIST = {}
self._FILTERS=kwargs
def summary(self):
"""
Get the episodes summary for a specific show id and sets
them to their attributes.
Returns a dict with a summary of the episodes.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showeps = tvdb.Series_Episodes(78804)
>>> response = showeps.summary()
>>> showeps.airedEpisodes
'267'
"""
path = self._get_id_path('summary')
response = self._GET(path)
self._set_attrs_to_values(response)
return response
def query_params(self):
"""
Get the query parameters allowed for a specific show id.
Returns a dict with all the filters allowed.
"""
path = self._get_id_path('query_params')
response = self._GET(path)
self._set_attrs_to_values({'query_params': response})
return response
def pages(self):
"""
Get the number of episode pages for filtered episodes of a specific show id.
Returns the integer number of pages for filtered episodes of the show.
"""
if self._PAGES < 0:
self.page(1)
return self._PAGES
def all(self):
"""
Get the full episode list with basic details for a specific show id.
Returns a list of episodes with basic info.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showeps = tvdb.Series_Episodes(78804)
>>> response = showeps.all()
>>> showeps.episodes[0]['episodeName']
'Rose'
"""
episodes = []
for i in range (1, self.pages()+1):
episodes.extend(self.page(i))
self._set_attrs_to_values({'episodes': episodes})
return episodes
def page(self, page):
"""
Get the episode list for a specific page of a show id.
`page` is the page number of the episodes list to retrieve
Returns a list episodes with basic info.
"""
if page in self._PAGES_LIST:
return self._PAGES_LIST[page]
if self._FILTERS:
path = self._get_id_path('query')
else:
path = self._get_id_path('episodes')
filters = self._FILTERS.copy()
filters['page'] = page
response = self._GET(path, params=filters, cleanJson=False)
if 'links' in response and 'last' in response['links']:
self._PAGES = response['links']['last']
self._PAGES_LIST[page] = response['data']
return response['data']
def __iter__(self):
for i in range (1, self.pages()+1):
yield self.page(i)
Ancestors (in MRO)
- Series_Episodes
- tvdbsimple.base.TVDB
- builtins.object
Static methods
def __init__(
self, id, language='', **kwargs)
Initialize the class.
id
is the TheTVDb series id.
You can provide language
, the language id you want to use to
retrieve the info.
You can provide absoluteNumber
to get only episodes with the
provided absolute number.
You can provide airedSeason
to get only episodes with the
provided aired season number.
You can provide airedEpisode
to get only episodes with the
provided aired episode number.
You can provide dvdSeason
to get only episodes with the
provided dvd season number.
You can provide dvdEpisode
to get only episodes with the
provided dvd episode number.
You can provide imdbId
to get only episodes with the
provided imdb id.
def __init__(self, id, language='', **kwargs):
"""
Initialize the class.
`id` is the TheTVDb series id.
You can provide `language`, the language id you want to use to
retrieve the info.
You can provide `absoluteNumber` to get only episodes with the
provided absolute number.
You can provide `airedSeason` to get only episodes with the
provided aired season number.
You can provide `airedEpisode` to get only episodes with the
provided aired episode number.
You can provide `dvdSeason` to get only episodes with the
provided dvd season number.
You can provide `dvdEpisode` to get only episodes with the
provided dvd episode number.
You can provide `imdbId` to get only episodes with the
provided imdb id.
"""
super(Series_Episodes, self).__init__(id)
self._set_language(language)
self.update_filters(**kwargs)
def all(
self)
Get the full episode list with basic details for a specific show id.
Returns a list of episodes with basic info.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showeps = tvdb.Series_Episodes(78804)
>>> response = showeps.all()
>>> showeps.episodes[0]['episodeName']
'Rose'
def all(self):
"""
Get the full episode list with basic details for a specific show id.
Returns a list of episodes with basic info.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showeps = tvdb.Series_Episodes(78804)
>>> response = showeps.all()
>>> showeps.episodes[0]['episodeName']
'Rose'
"""
episodes = []
for i in range (1, self.pages()+1):
episodes.extend(self.page(i))
self._set_attrs_to_values({'episodes': episodes})
return episodes
def get_token(
self, forceNew=False)
Get the existing token or creates it if it doesn't exist. Returns the API token.
If forceNew
is true the function will do a new login to retrieve the token.
def get_token(self, forceNew=False):
"""
Get the existing token or creates it if it doesn't exist.
Returns the API token.
If `forceNew` is true the function will do a new login to retrieve the token.
"""
from . import KEYS
if not KEYS.API_TOKEN or forceNew:
if not KEYS.API_KEY:
raise APIKeyError
if hasattr(self,"USER") and hasattr(self,"USER_KEY"):
data = {"apikey": KEYS.API_KEY, "username": self.USER, "userkey": self.USER_KEY}
else:
data={"apikey": KEYS.API_KEY}
response = requests.request(
'POST', self._get_complete_url('login'),
data=json.dumps(data),
headers=self._headers)
if response.status_code == 200:
KEYS.API_TOKEN = response.json()['token']
else:
error = "Unknown error while authenticating. Check your api key or your user/userkey"
try:
error = response.json()['error']
except:
pass
raise AuthenticationError(error)
return KEYS.API_TOKEN
def page(
self, page)
Get the episode list for a specific page of a show id.
page
is the page number of the episodes list to retrieve
Returns a list episodes with basic info.
def page(self, page):
"""
Get the episode list for a specific page of a show id.
`page` is the page number of the episodes list to retrieve
Returns a list episodes with basic info.
"""
if page in self._PAGES_LIST:
return self._PAGES_LIST[page]
if self._FILTERS:
path = self._get_id_path('query')
else:
path = self._get_id_path('episodes')
filters = self._FILTERS.copy()
filters['page'] = page
response = self._GET(path, params=filters, cleanJson=False)
if 'links' in response and 'last' in response['links']:
self._PAGES = response['links']['last']
self._PAGES_LIST[page] = response['data']
return response['data']
def pages(
self)
Get the number of episode pages for filtered episodes of a specific show id.
Returns the integer number of pages for filtered episodes of the show.
def pages(self):
"""
Get the number of episode pages for filtered episodes of a specific show id.
Returns the integer number of pages for filtered episodes of the show.
"""
if self._PAGES < 0:
self.page(1)
return self._PAGES
def query_params(
self)
Get the query parameters allowed for a specific show id.
Returns a dict with all the filters allowed.
def query_params(self):
"""
Get the query parameters allowed for a specific show id.
Returns a dict with all the filters allowed.
"""
path = self._get_id_path('query_params')
response = self._GET(path)
self._set_attrs_to_values({'query_params': response})
return response
def refresh_token(
self)
Refresh the current token set in the module.
Returns the new obtained valid token for the API.
def refresh_token(self):
"""
Refresh the current token set in the module.
Returns the new obtained valid token for the API.
"""
self._set_token_header()
response = requests.request(
'GET', self._get_complete_url('refresh_token'),
headers=self._headers)
response.raise_for_status()
jsn = response.json()
if 'token' in jsn:
from . import KEYS
KEYS.API_TOKEN = jsn['token']
return KEYS.API_TOKEN
return ''
def summary(
self)
Get the episodes summary for a specific show id and sets them to their attributes.
Returns a dict with a summary of the episodes.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showeps = tvdb.Series_Episodes(78804)
>>> response = showeps.summary()
>>> showeps.airedEpisodes
'267'
def summary(self):
"""
Get the episodes summary for a specific show id and sets
them to their attributes.
Returns a dict with a summary of the episodes.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showeps = tvdb.Series_Episodes(78804)
>>> response = showeps.summary()
>>> showeps.airedEpisodes
'267'
"""
path = self._get_id_path('summary')
response = self._GET(path)
self._set_attrs_to_values(response)
return response
def update_filters(
self, **kwargs)
Set the filters for the episodes of the specific show id.
You can provide absoluteNumber
to get only episodes with the
provided absolute number.
You can provide airedSeason
to get only episodes with the
provided aired season number.
You can provide airedEpisode
to get only episodes with the
provided aired episode number.
You can provide dvdSeason
to get only episodes with the
provided dvd season number.
You can provide dvdEpisode
to get only episodes with the
provided dvd episode number.
You can provide imdbId
to get only episodes with the
provided imdb id.
def update_filters(self, **kwargs):
"""
Set the filters for the episodes of the specific show id.
You can provide `absoluteNumber` to get only episodes with the
provided absolute number.
You can provide `airedSeason` to get only episodes with the
provided aired season number.
You can provide `airedEpisode` to get only episodes with the
provided aired episode number.
You can provide `dvdSeason` to get only episodes with the
provided dvd season number.
You can provide `dvdEpisode` to get only episodes with the
provided dvd episode number.
You can provide `imdbId` to get only episodes with the
provided imdb id.
"""
self._PAGES = -1
self._PAGES_LIST = {}
self._FILTERS=kwargs
class Series_Images
Class needed to organize series images. Allow to retrieve all the types of images of a series. Requires the series id.
language: (optional) language to request.
resolution: (optional) image resolution.
subKey: (optional) subkey research.
class Series_Images(TVDB):
"""
Class needed to organize series images. Allow to retrieve all
the types of images of a series.
Requires the series id.
language: (optional) language to request.
resolution: (optional) image resolution.
subKey: (optional) subkey research.
"""
_BASE_PATH = 'series'
_URLS = {
'imagequery': '/{id}/images/query',
'summary': '/{id}/images',
'queryparams': '/{id}/images/query/params'
}
def __init__(self, id, language='', **kwargs):
"""
Initialize the class.
`id` is the TheTVDb series id.
You can provide `language`, the language id you want to use to
retrieve the info.
You can provide `reqolution` to get only episodes with the
provided resolution.
You can provide `subKey` to get only episodes with the
provided subKey.
"""
super(Series_Images, self).__init__(id)
self._set_language(language)
self.update_filters(**kwargs)
def update_filters(self, **kwargs):
"""
Set the filters for the episodes of the specific show id.
You can provide `language`, the language id you want to use to
retrieve the info.
You can provide `reqolution` to get only episodes with the
provided resolution.
You can provide `subKey` to get only episodes with the
provided subKey.
"""
self._FILTERS=kwargs
def summary(self):
"""
Get the images summary for a specific show id and sets
them to `summary` attributes.
Returns a dict with a summary of the images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.summary()
>>> showimgs.summary['poster']
53
"""
path = self._get_id_path('summary')
response = self._GET(path)
self._set_attrs_to_values(response)
return response
def query_params(self):
"""
Get the query parameters allowed for a specific show id.
Returns:
A dict respresentation of the JSON returned from the API.
"""
path = self._get_id_path('query_params')
response = self._GET(path)
self._set_attrs_to_values({'query_params': response})
return response
def poster(self, language=''):
"""
Get the posters for a specific show.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of posters.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.poster()
>>> showimgs.poster[0]['resolution']
'680x1000'
"""
return self._get_image_type('poster', language)
def fanart(self, language=''):
"""
Get the fanarts for a specific show.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of fanarts.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.fanart()
>>> showimgs.fanart[0]['resolution']
'1280x720'
"""
return self._get_image_type('fanart', language)
def series(self, language=''):
"""
Get the series images for a specific show.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of series images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.series()
>>> showimgs.series[0]['thumbnail']
'_cache/text/34391.jpg'
"""
return self._get_image_type('series', language)
def season(self, language=''):
"""
Get the season images for a specific show.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of season images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.season()
>>> showimgs.season[0]['thumbnail']
'_cache/seasons/34391-1.jpg'
"""
return self._get_image_type('season', language)
def seasonwide(self, language=''):
"""
Get the seasonwide images for a specific show.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of seasonwide images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.seasonwide()
>>> showimgs.seasonwide[0]['thumbnail']
'_cache/seasonswide/78804-1.jpg'
"""
return self._get_image_type('seasonwide', language)
def all(self, language=''):
"""
Get all the images for a specific show and sets it to `images` attribute.
It needs to have at least one filter set.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804, resolution='1280x720')
>>> response = showimgs.all()
>>> showimgs.images[0]['resolution']
'1280x720'
"""
return self._get_image_type('images', language)
def _get_image_type(self, type, language=''):
path = self._get_id_path('imagequery')
self._set_language(language)
filters = self._FILTERS.copy()
if type != 'images':
filters['keyType'] = type
response = self._GET(path, params=filters)
self._set_attrs_to_values({type: response})
return response
Ancestors (in MRO)
- Series_Images
- tvdbsimple.base.TVDB
- builtins.object
Static methods
def __init__(
self, id, language='', **kwargs)
Initialize the class.
id
is the TheTVDb series id.
You can provide language
, the language id you want to use to
retrieve the info.
You can provide reqolution
to get only episodes with the
provided resolution.
You can provide subKey
to get only episodes with the
provided subKey.
def __init__(self, id, language='', **kwargs):
"""
Initialize the class.
`id` is the TheTVDb series id.
You can provide `language`, the language id you want to use to
retrieve the info.
You can provide `reqolution` to get only episodes with the
provided resolution.
You can provide `subKey` to get only episodes with the
provided subKey.
"""
super(Series_Images, self).__init__(id)
self._set_language(language)
self.update_filters(**kwargs)
def all(
self, language='')
Get all the images for a specific show and sets it to images
attribute.
It needs to have at least one filter set.
You can provide language
, the language id you want to use to
retrieve the info.
Returns a list of images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804, resolution='1280x720')
>>> response = showimgs.all()
>>> showimgs.images[0]['resolution']
'1280x720'
def all(self, language=''):
"""
Get all the images for a specific show and sets it to `images` attribute.
It needs to have at least one filter set.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804, resolution='1280x720')
>>> response = showimgs.all()
>>> showimgs.images[0]['resolution']
'1280x720'
"""
return self._get_image_type('images', language)
def fanart(
self, language='')
Get the fanarts for a specific show.
You can provide language
, the language id you want to use to
retrieve the info.
Returns a list of fanarts.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.fanart()
>>> showimgs.fanart[0]['resolution']
'1280x720'
def fanart(self, language=''):
"""
Get the fanarts for a specific show.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of fanarts.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.fanart()
>>> showimgs.fanart[0]['resolution']
'1280x720'
"""
return self._get_image_type('fanart', language)
def get_token(
self, forceNew=False)
Get the existing token or creates it if it doesn't exist. Returns the API token.
If forceNew
is true the function will do a new login to retrieve the token.
def get_token(self, forceNew=False):
"""
Get the existing token or creates it if it doesn't exist.
Returns the API token.
If `forceNew` is true the function will do a new login to retrieve the token.
"""
from . import KEYS
if not KEYS.API_TOKEN or forceNew:
if not KEYS.API_KEY:
raise APIKeyError
if hasattr(self,"USER") and hasattr(self,"USER_KEY"):
data = {"apikey": KEYS.API_KEY, "username": self.USER, "userkey": self.USER_KEY}
else:
data={"apikey": KEYS.API_KEY}
response = requests.request(
'POST', self._get_complete_url('login'),
data=json.dumps(data),
headers=self._headers)
if response.status_code == 200:
KEYS.API_TOKEN = response.json()['token']
else:
error = "Unknown error while authenticating. Check your api key or your user/userkey"
try:
error = response.json()['error']
except:
pass
raise AuthenticationError(error)
return KEYS.API_TOKEN
def poster(
self, language='')
Get the posters for a specific show.
You can provide language
, the language id you want to use to
retrieve the info.
Returns a list of posters.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.poster()
>>> showimgs.poster[0]['resolution']
'680x1000'
def poster(self, language=''):
"""
Get the posters for a specific show.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of posters.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.poster()
>>> showimgs.poster[0]['resolution']
'680x1000'
"""
return self._get_image_type('poster', language)
def query_params(
self)
Get the query parameters allowed for a specific show id.
Returns: A dict respresentation of the JSON returned from the API.
def query_params(self):
"""
Get the query parameters allowed for a specific show id.
Returns:
A dict respresentation of the JSON returned from the API.
"""
path = self._get_id_path('query_params')
response = self._GET(path)
self._set_attrs_to_values({'query_params': response})
return response
def refresh_token(
self)
Refresh the current token set in the module.
Returns the new obtained valid token for the API.
def refresh_token(self):
"""
Refresh the current token set in the module.
Returns the new obtained valid token for the API.
"""
self._set_token_header()
response = requests.request(
'GET', self._get_complete_url('refresh_token'),
headers=self._headers)
response.raise_for_status()
jsn = response.json()
if 'token' in jsn:
from . import KEYS
KEYS.API_TOKEN = jsn['token']
return KEYS.API_TOKEN
return ''
def season(
self, language='')
Get the season images for a specific show.
You can provide language
, the language id you want to use to
retrieve the info.
Returns a list of season images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.season()
>>> showimgs.season[0]['thumbnail']
'_cache/seasons/34391-1.jpg'
def season(self, language=''):
"""
Get the season images for a specific show.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of season images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.season()
>>> showimgs.season[0]['thumbnail']
'_cache/seasons/34391-1.jpg'
"""
return self._get_image_type('season', language)
def seasonwide(
self, language='')
Get the seasonwide images for a specific show.
You can provide language
, the language id you want to use to
retrieve the info.
Returns a list of seasonwide images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.seasonwide()
>>> showimgs.seasonwide[0]['thumbnail']
'_cache/seasonswide/78804-1.jpg'
def seasonwide(self, language=''):
"""
Get the seasonwide images for a specific show.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of seasonwide images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.seasonwide()
>>> showimgs.seasonwide[0]['thumbnail']
'_cache/seasonswide/78804-1.jpg'
"""
return self._get_image_type('seasonwide', language)
def series(
self, language='')
Get the series images for a specific show.
You can provide language
, the language id you want to use to
retrieve the info.
Returns a list of series images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.series()
>>> showimgs.series[0]['thumbnail']
'_cache/text/34391.jpg'
def series(self, language=''):
"""
Get the series images for a specific show.
You can provide `language`, the language id you want to use to
retrieve the info.
Returns a list of series images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.series()
>>> showimgs.series[0]['thumbnail']
'_cache/text/34391.jpg'
"""
return self._get_image_type('series', language)
def summary(
self)
Get the images summary for a specific show id and sets
them to summary
attributes.
Returns a dict with a summary of the images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.summary()
>>> showimgs.summary['poster']
53
def summary(self):
"""
Get the images summary for a specific show id and sets
them to `summary` attributes.
Returns a dict with a summary of the images.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> showimgs = tvdb.Series_Images(78804)
>>> response = showimgs.summary()
>>> showimgs.summary['poster']
53
"""
path = self._get_id_path('summary')
response = self._GET(path)
self._set_attrs_to_values(response)
return response
def update_filters(
self, **kwargs)
Set the filters for the episodes of the specific show id.
You can provide language
, the language id you want to use to
retrieve the info.
You can provide reqolution
to get only episodes with the
provided resolution.
You can provide subKey
to get only episodes with the
provided subKey.
def update_filters(self, **kwargs):
"""
Set the filters for the episodes of the specific show id.
You can provide `language`, the language id you want to use to
retrieve the info.
You can provide `reqolution` to get only episodes with the
provided resolution.
You can provide `subKey` to get only episodes with the
provided subKey.
"""
self._FILTERS=kwargs