Top

tvdbsimple.search module

This module implements the Search functionality of TheTVDb API. Allows to search for tv series in the db.

See Search API section

# -*- 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