Initial commit

Author: razzeee

LICENSE.txt

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<addon id="script.module.tvdbsimple" name="tvdbsimple" version="1.0.4" provider-name="phate89">
+    <requires>
+        <import addon="xbmc.python" version="3.0.0"/>
+        <import addon="script.module.requests" version="2.9.1"/>
+    </requires>
+    <extension point="xbmc.python.module" library="lib" />
+    <extension point="xbmc.addon.metadata">
+        <summary lang="en">tvdbsimple module</summary>
+        <description lang="en">Helper module for thetvdb site access</description>
+        <platform>all</platform>
+        <license>GPLv3</license>
+        <source>https://github.com/phate89/tvdbsimple</source>
+    </extension>
+</addon>

addon.xml

@@ -0,0 +1,4 @@
+1.0.0
+- Initial release
+
+

changelog.txt

@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+
+"""
+`tvdbsimple` is a wrapper, written in Python, for TheTVDb.com 
+API v2.  By calling the functions available in `tvdbsimple` you can simplify 
+your code and easily access a vast amount of tv and cast data. To find 
+out more about TheTVDb API, check out the [official api page](https://api.thetvdb.com/swagger/)
+
+Features
+--------
+
+- Full API implementation. Supports Search, Series, Episode, Updated, User and Languages methods.
+- Updated with the latest JSON API. 
+- Fully tested with automated tests and travis.ci.
+- Supports Python 2.7, 3.3, 3.4, 3.5, 3.6.
+- Easy to access data using Python class attributes.
+- Easy to experiment with `tvdbsimple` functions inside the Python interpreter.
+
+Installation
+------------
+
+`tvdbsimple` is available on the [Python Package Index](https://pypi.python.org/pypi/tvdbsimple).
+
+You can install `tvdbsimple` using one of the following techniques:
+
+- Use pip:  `pip install tvdbsimple`
+- Download the .zip or .tar.gz file from PyPI and install it yourself
+- Download the [source from Github](http://github.com/phate89/tvdbsimple) and install it yourself
+
+If you install it yourself, also install [requests](http://www.python-requests.org/en/latest).
+
+API Key
+-------
+You will need an API key to TheTVDb to access the API.  To obtain a key, follow these steps:
+
+1) Register for and verify an [account](http://thetvdb.com/?tab=register).
+2) [Log into](http://thetvdb.com/?tab=login) your account.
+3) [Go to this page](http://thetvdb.com/?tab=apiregister) and fill your details to generate a new API key.
+
+Examples
+--------
+All the functions are fully documented here but you can find several use examples in the [examples page](https://github.com/phate89/tvdbsimple/blob/master/EXAMPLES.rst).
+
+License
+-------
+The module is distributed with a GPLv3 license, see [LICENSE](https://www.gnu.org/licenses/gpl-3.0.en.html) for more details
+
+copyright (c) 2017 by phate89.
+"""
+
+__title__ = 'tvdbsimple'
+__version__ = '1.0.4'
+__author__ = 'phate89'
+__copyright__ = 'Copyright © 2017 phate89'
+__license__ = 'GPLv3'
+
+from .base import APIKeyError
+from .keys import keys
+from .search import Search
+from .series import Series, Series_Episodes, Series_Images
+from .languages import Languages
+from .episode import Episode
+from .updates import Updates
+from .user import User, User_Ratings
+
+KEYS=keys()
+"""
+Contains `API_KEY` and `API_TOKEN`.
+
+To use the module you have to set at least the `API_KEY` value (THETVDb api key).
+You can also provide an `API_TOKEN` if you already have a valid one stored. If the 
+valid token doesn't work anymore the module will try to retrieve a new one
+using the `API_KEY` variable
+"""

icon.png

@@ -0,0 +1,172 @@
+# -*- coding: utf-8 -*-
+
+"""
+This module implements the base class of tvdbsimple.
+
+Handle automatically login, token creation and response basic stripping.
+
+[See Authentication API section](https://api.thetvdb.com/swagger#!/Authentication)
+"""
+
+import json
+import requests
+
+
+class AuthenticationError(Exception):
+    """
+    Authentication exception class for authentication errors
+    """
+    pass
+
+class APIKeyError(Exception):
+    """
+    Missing API key exception class in case of missing api
+    """
+    pass
+
+class TVDB(object):
+    """
+    Basic Authentication class for API key, login and token automatic handling functionality.
+
+    [See Authentication API section](https://api.thetvdb.com/swagger#!/Authentication)
+    """
+    _headers = {'Content-Type': 'application/json',
+               'Accept': 'application/json',
+               'Connection': 'close'}
+    _BASE_PATH = ''
+    _URLS = {}
+    _BASE_URI = 'https://api.thetvdb.com'
+
+    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_path(self, key):
+        return self._BASE_PATH + self._URLS[key]
+
+    def _get_id_path(self, key):
+        return self._get_path(key).format(id=self._ID)
+
+    def _get_complete_url(self, path):
+        return '{base_uri}/{path}'.format(base_uri=self._BASE_URI, path=path)
+
+    def _set_language(self, language):
+        if language:
+            self._headers['Accept-Language'] = language
+    
+    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 _set_token_header(self, forceNew=False):
+        self._headers['Authorization'] = 'Bearer ' + self.get_token(forceNew)
+
+    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 _request(self, method, path, params=None, payload=None, forceNewToken=False, cleanJson = True):
+        self._set_token_header(forceNewToken)
+        
+        url = self._get_complete_url(path)
+
+        response = requests.request(
+            method, url, params=params, 
+            data=json.dumps(payload) if payload else payload,
+            headers=self._headers)
+        
+        if response.status_code == 200:
+            response.encoding = 'utf-8'
+            jsn = response.json()
+            if cleanJson and 'data' in jsn:
+                return jsn['data']
+            return jsn
+        elif not forceNewToken:
+            return self._request(method=method, path=path, params=params, payload=payload, forceNewToken=True)
+        try:
+            raise Exception(response.json()['error'])
+        except:
+            response.raise_for_status()
+
+    def _GET(self, path, params=None, cleanJson = True):
+        return self._request('GET', path, params=params, cleanJson=cleanJson)
+
+    def _POST(self, path, params=None, payload=None, cleanJson = True):
+        return self._request('POST', path, params=params, payload=payload, cleanJson=cleanJson)
+
+    def _DELETE(self, path, params=None, payload=None, cleanJson = True):
+        return self._request('DELETE', path, params=params, payload=payload, cleanJson=cleanJson)
+
+    def _PUT(self, path, params=None, payload=None, cleanJson = True):
+        return self._request('PUT', path, params=params, payload=payload, cleanJson=cleanJson)
+
+    def _set_attrs_to_values(self, response={}):
+        """
+        Set attributes to dictionary values.
+
+        - e.g.
+        >>> import tvdbsimple as tvdb
+        >>> show = tmdb.Tv(10332)
+        >>> response = show.info()
+        >>> show.title  # instead of response['title']
+        """
+        if isinstance(response, dict):
+            for key in response:
+                setattr(self, key, response[key])

lib/__init__.py

@@ -0,0 +1,55 @@
+# -*- coding: utf-8 -*-
+
+"""
+This module implements the Episode functionality of TheTVDb API.
+Allows to retrieve episode detailed info.
+
+See [Episodes API section](https://api.thetvdb.com/swagger#!/Episodes)
+"""
+
+from .base import TVDB
+
+class Episode(TVDB):
+    """
+    Episode class to retrieve detailed info about an episode.
+    Requires the episode id.
+    """
+    _BASE_PATH = 'episodes'
+    _URLS = {
+        'info': '/{id}'
+    }
+
+    def __init__(self, id, language=''):
+        """
+        Initialize the episode class.
+
+        `id` is the TheTVDb episode id. You can also provide `language`, 
+        the language id you want to use to retrieve the info.
+        """
+        super(Episode, self).__init__(id)
+        self._set_language(language)
+
+    def info(self, language=''):
+        """
+        Get the episode information of the episode and set its values to the local attributes.
+
+        You can set `language` with the language id to retrieve info in that specific language.
+
+        It returns a dictionary with all the episode info.
+
+        For example
+
+            #!python
+            >>> import tvdbsimple as tvdb
+            >>> tvdb.KEYS.API_KEY = 'YOUR_API_KEY'
+            >>> ep = tvdb.Episode(5330530)
+            >>> ep.imdbId
+            'tt4701544'
+
+        """
+        path = self._get_id_path('info')
+        
+        self._set_language(language)
+        response = self._GET(path)
+        self._set_attrs_to_values(response)
+        return response

lib/tvdbsimple/__init__.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+
+"""
+This module implements the keys class of tvdbsimple.
+"""
+
+import os
+class keys():
+    """
+    The class is needed to hold the api key value and the token value.
+    """
+    API_KEY = os.environ.get('TVDB_API_KEY', None)
+    """
+    It's the TheTVDb api key needed for the api access. The developer must fill it.
+    """
+    API_TOKEN = os.environ.get('TVDB_API_TOKEN', None)
+    """
+    Contains the TheTVDb token used for authenticating api requests. The developer might provide a valid one.
+    
+    If a request fails the module will get a new token automatically upating it.
+    """