tvdbsimple.search module
This module implements the Search functionality of TheTVDb API. Allows to search for tv series in the db.
# -*- coding: utf-8 -*-
"""
This module implements the Search functionality of TheTVDb API.
Allows to search for tv series in the db.
See [Search API section](https://api.thetvdb.com/swagger#!/Search)
"""
from .base import TVDB
class Search(TVDB):
"""
Class that allow to search for series with filters.
"""
_BASE_PATH = 'search'
_URLS = {
'series': '/series',
'seriesparams': '/series/params'
}
def series(self, name='', imdbId='', zap2itId='', language=''):
"""
Search series with the information provided.
You can set `name` to search for a series with that name. You can set `imdbId`
to search a series with the provided imdb id. You can set `zap2itId`
to search a series with the provided zap2it id. You can set `language` to
retrieve the results with the provided language.
Returns a list series with basic information that matches your search.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> search = tvdb.Search()
>>> reponse = search.series("doctor who 2005")
>>> search.series[0]['seriesName']
'Doctor Who (2005)'
"""
path = self._get_path('series')
filters = {}
if name:
filters['name'] = name
if imdbId:
filters['imdbId'] = imdbId
if zap2itId:
filters['zap2itId'] = zap2itId
self._set_language(language)
response = self._GET(path, params=filters)
self._set_attrs_to_values({'series': response})
return response
def series_params(self):
"""
Return the available search params.
Returns:
A dict respresentation of the JSON returned from the API.
"""
path = self._get_path('series_params')
response = self._GET(path)
self._set_attrs_to_values({'series_params': response})
return response
Classes
class Search
Class that allow to search for series with filters.
class Search(TVDB):
"""
Class that allow to search for series with filters.
"""
_BASE_PATH = 'search'
_URLS = {
'series': '/series',
'seriesparams': '/series/params'
}
def series(self, name='', imdbId='', zap2itId='', language=''):
"""
Search series with the information provided.
You can set `name` to search for a series with that name. You can set `imdbId`
to search a series with the provided imdb id. You can set `zap2itId`
to search a series with the provided zap2it id. You can set `language` to
retrieve the results with the provided language.
Returns a list series with basic information that matches your search.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> search = tvdb.Search()
>>> reponse = search.series("doctor who 2005")
>>> search.series[0]['seriesName']
'Doctor Who (2005)'
"""
path = self._get_path('series')
filters = {}
if name:
filters['name'] = name
if imdbId:
filters['imdbId'] = imdbId
if zap2itId:
filters['zap2itId'] = zap2itId
self._set_language(language)
response = self._GET(path, params=filters)
self._set_attrs_to_values({'series': response})
return response
def series_params(self):
"""
Return the available search params.
Returns:
A dict respresentation of the JSON returned from the API.
"""
path = self._get_path('series_params')
response = self._GET(path)
self._set_attrs_to_values({'series_params': response})
return response
Ancestors (in MRO)
- Search
- tvdbsimple.base.TVDB
- builtins.object
Static methods
def __init__(
self, id=0, user=None, key=None)
Initialize the base class.
You can provide id
that is the item id used for url creation. You can also
provide user
, that is the username for login.
You can also provide key
, that is the userkey needed to
authenticate with the user, you can find it in the
account info under account identifier.,
the language id you want to use to retrieve the info.
def __init__(self, id=0, user=None, key=None):
"""
Initialize the base class.
You can provide `id` that is the item id used for url creation. You can also
provide `user`, that is the username for login.
You can also provide `key`, that is the userkey needed to
authenticate with the user, you can find it in the
[account info](http://thetvdb.com/?tab=userinfo) under account identifier.,
the language id you want to use to retrieve the info.
"""
self._ID = id
self.USER = user
"""Stores username if available"""
self.USER_KEY = key
"""Stores user-key if available"""
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 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 series(
self, name='', imdbId='', zap2itId='', language='')
Search series with the information provided.
You can set name
to search for a series with that name. You can set imdbId
to search a series with the provided imdb id. You can set zap2itId
to search a series with the provided zap2it id. You can set language
to
retrieve the results with the provided language.
Returns a list series with basic information that matches your search.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> search = tvdb.Search()
>>> reponse = search.series("doctor who 2005")
>>> search.series[0]['seriesName']
'Doctor Who (2005)'
def series(self, name='', imdbId='', zap2itId='', language=''):
"""
Search series with the information provided.
You can set `name` to search for a series with that name. You can set `imdbId`
to search a series with the provided imdb id. You can set `zap2itId`
to search a series with the provided zap2it id. You can set `language` to
retrieve the results with the provided language.
Returns a list series with basic information that matches your search.
For example
#!python
>>> import tvdbsimple as tvdb
>>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
>>> search = tvdb.Search()
>>> reponse = search.series("doctor who 2005")
>>> search.series[0]['seriesName']
'Doctor Who (2005)'
"""
path = self._get_path('series')
filters = {}
if name:
filters['name'] = name
if imdbId:
filters['imdbId'] = imdbId
if zap2itId:
filters['zap2itId'] = zap2itId
self._set_language(language)
response = self._GET(path, params=filters)
self._set_attrs_to_values({'series': response})
return response
def series_params(
self)
Return the available search params.
Returns: A dict respresentation of the JSON returned from the API.
def series_params(self):
"""
Return the available search params.
Returns:
A dict respresentation of the JSON returned from the API.
"""
path = self._get_path('series_params')
response = self._GET(path)
self._set_attrs_to_values({'series_params': response})
return response