Series expansion (#9)

* allow pulling all episodes when pulling a series

* add __slots__

* provide timeout property

* add strict parameter

* add changelog

Author: barrust

CHANGELOG.md

@@ -0,0 +1,26 @@
+
+## Version 0.1.0
+* Added `timeout` property
+* Added ability to pull all episodes when pulling a series (optional)
+* `strict` property allows for swallowing exceptions
+* Use __slots__
+
+## Version 0.0.4
+* Search pulls all results unless specified not to do so
+* Added additional exceptions
+    * OMDBTooManyResults
+    * OMDBInvalidAPIKey
+* Added ability to set the API key
+* Convert dictionary from camelCase to snake_case
+
+## Version 0.0.3
+* Added doc strings for online documentation and deployed to [readthedocs.org](https://pyomdbapi.readthedocs.io/en/latest/)
+* Fixed a call to the formatting of results
+
+## Version 0.0.2
+* Fixed error with formatting the results
+
+## Version 0.0.1
+* Initial Release
+   * Search by movie or series name
+   * Get movie, series, or episode by name or IMDBid

README.rst

@@ -5,11 +5,16 @@ A simple OMDB API python wrapper
 
 .. image:: https://badge.fury.io/py/pyomdbapi.svg
     :target: https://badge.fury.io/py/pyomdbapi
+    :alt: PyPy Version
 .. image:: https://api.codacy.com/project/badge/Grade/e83dad34f35a44dea103100f23cd6310
     :target: https://www.codacy.com/app/barrust/pyomdbapi?utm_source=github.com&utm_medium=referral&utm_content=barrust/pyomdbapi&utm_campaign=Badge_Grade
+    :alt: Code Quality
 .. image:: https://img.shields.io/badge/license-MIT-blue.svg
     :target: https://opensource.org/licenses/MIT/
     :alt: License
+.. image:: https://pepy.tech/badge/pyomdbapi
+    :target: https://pepy.tech/project/pyomdbapi
+    :alt: Downloads
 
 Documenation
 -------------------------------------------------------------------------------

omdb/__init__.py

@@ -7,7 +7,7 @@
 __maintainer__ = 'Tyler Barrus'
 __email__ = 'barrust@gmail.com'
 __license__ = 'MIT'
-__version__ = '0.0.4'
+__version__ = '0.1.0'
 __url__ = 'https://github.com/barrust/pyomdbapi'
 __bugtrack_url__ = '{0}/issues'.format(__url__)
 __all__ = ['OMDB', 'OMDBException', 'OMDBNoResults', 'OMDBLimitReached', 'OMDBTooManyResults']

omdb/omdb.py

@@ -4,7 +4,7 @@
 import requests
 
 from .exceptions import OMDBException, OMDBNoResults, OMDBLimitReached, OMDBTooManyResults, OMDBInvalidAPIKey
-from .utilities import camelcase_to_snake_case, range_inclusive
+from .utilities import camelcase_to_snake_case, range_inclusive, to_int
 
 
 class OMDB(object):
@@ -13,15 +13,24 @@ class OMDB(object):
         Args:
             api_key (str): The API Key to use for the requests
             timeout (float): The timeout, in seconds
+            strict (bool): To use strict error checking or not; strict (True) \
+            will throw errors if the API returns an error code, non-strict will not
         Returns:
-            OMDB: An OMDB API wrapper connection object '''
+            OMDB: An OMDB API wrapper connection object
+        Note:
+            With `strict` disabled, it is up to the user to check for and handle errors '''
 
-    def __init__(self, api_key, timeout=5):
+    __slots__ = ['_api_url', '_timeout', '_api_key', '_session', '_strict']
+
+    def __init__(self, api_key, timeout=5, strict=True):
         ''' the init object '''
         self._api_url = 'https://www.omdbapi.com/'
-        self._timeout = timeout
+        self._timeout = None
+        self.timeout = timeout
         self._api_key = None
         self.api_key = api_key
+        self._strict = None
+        self.strict = strict
         self._session = requests.Session()
 
     def close(self):
@@ -43,6 +52,30 @@ def api_key(self, val):
         else:
             raise OMDBInvalidAPIKey(val)
 
+    @property
+    def timeout(self):
+        ''' float: The timeout parameter to pass to requests for how long to wait '''
+        return self._timeout
+
+    @timeout.setter
+    def timeout(self, val):
+        ''' set the timeout property '''
+        try:
+            self._timeout = float(val)
+        except ValueError:
+            msg = "OMDB Timeout must be a float or convertable to float! {} provided".format(val)
+            raise ValueError(msg)
+
+    @property
+    def strict(self):
+        ''' bool: Whether to throw or swallow errors; True will throw exceptions '''
+        return self._strict
+
+    @strict.setter
+    def strict(self, val):
+        ''' set the strict property '''
+        self._strict = bool(val)
+
     def search(self, title, pull_all_results=True, page=1, **kwargs):
         ''' Perform a search based on title
 
@@ -101,7 +134,7 @@ def get(self, title=None, imdbid=None, **kwargs):
         }
         if imdbid:
             params['i'] = imdbid
-        if title:
+        elif title:
             params['t'] = title
         else:
             raise OMDBException("Either title or imdbid is required!")
@@ -153,20 +186,32 @@ def get_movie(self, title=None, imdbid=None, **kwargs):
         params.update(kwargs)
         return self.get(title, imdbid, **params)
 
-    def get_series(self, title=None, imdbid=None, **kwargs):
+    def get_series(self, title=None, imdbid=None, pull_episodes=False, **kwargs):
         ''' Retrieve a TV series information by title or IMDB id
 
             Args:
                 title (str): The name of the movie to retrieve
                 imdbid (str): The IMDB id of the movie to retrieve
+                pull_episodes (bool): `True` to pull the episodes
                 kwargs (dict): the kwargs to add additional parameters to the API request
             Returns:
                 dict: A dictionary of all the results
             Note:
                 Either `title` or `imdbid` is required '''
         params = {'type': 'series'}
         params.update(kwargs)
-        return self.get(title, imdbid, **params)
+        res = self.get(title, imdbid, **params)
+        num_seasons = 0
+        if pull_episodes:
+            num_seasons = to_int(res.get('total_seasons', 0))
+            res['seasons'] = dict()
+
+        for i in range(num_seasons):
+            season_num = i + 1
+            season = self.get_episodes(title, imdbid, season=season_num)
+            res['seasons'][season_num] = season
+
+        return res
 
     def get_episode(self, title=None, imdbid=None, season=1, episode=1, **kwargs):
         ''' Retrieve a TV series episode by title or IMDB id and season and episode number
@@ -187,7 +232,7 @@ def get_episode(self, title=None, imdbid=None, season=1, episode=1, **kwargs):
         if episode:
             params['Episode'] = episode
         params.update(kwargs)
-        return self.get(title, imdbid, **params)
+        return self.get(title=title, imdbid=imdbid, **params)
 
     def get_episodes(self, title=None, imdbid=None, season=1, **kwargs):
         ''' Retrieve all episodes of a TV series by season number
@@ -201,7 +246,7 @@ def get_episodes(self, title=None, imdbid=None, season=1, **kwargs):
                 dict: A dictionary of all the results
             Note:
                 Either `title` or `imdbid` is required '''
-        return self.get_episode(title, imdbid, season, None, **kwargs)
+        return self.get_episode(title=title, imdbid=imdbid, season=season, episode=None, **kwargs)
 
     def _get_response(self, kwargs):
         ''' wrapper for the `requests` library call '''
@@ -231,7 +276,7 @@ def __format_results(self, res, params):
             res[camelcase_to_snake_case(key)] = val
 
         # NOTE: I dislike having to use string comparisons to check for specific error conditions
-        if 'response' in res and res['response'] == 'False':
+        if self.strict and 'response' in res and res['response'] == 'False':
             err = res.get('error', '').lower()
             if err == 'too many results.':
                 raise OMDBTooManyResults(res['error'], params)

omdb/utilities.py

@@ -31,3 +31,17 @@ def range_inclusive(start, end, step=1):
     '''
     for i in range(start, end + 1, step):
         yield i
+
+
+def to_int(val):
+    ''' Turn the passed in variable into an int; returns 0 if errors
+
+        Args:
+            val (str): The variable to turn into an int
+        Returns:
+            int: The int value if possible, 0 if an error occurs
+    '''
+    try:
+        return int(val)
+    except ValueError:
+        return 0