Metadata-Version: 1.1
Name: omdb
Version: 0.10.1
Summary: Python wrapper for OMDb API: http://www.omdbapi.com/
Home-page: https://github.com/dgilland/omdb.py
Author: Derrick Gilland
Author-email: dgilland@gmail.com
License: MIT License
Description: *******
        omdb.py
        *******
        
        |version| |travis| |coveralls| |license|
        
        Python wrapper around ``The Open Movie Database API`` (a.k.a. ``OMDb API``): http://omdbapi.com/
        
        **NOTE:** This library and its author are not endorsed by or affiliated with `OMDbAPI.com <http://omdbapi.com/>`_.
        
        
        Installation
        ============
        
        Using ``pip``:
        
        
        ::
        
        	pip install omdb
        
        
        Dependencies
        ============
        
        - requests >= 2.0.1
        
        
        API
        ===
        
        Each ``omdb.py`` method supports the same parameters as the ``OMDb API``.
        
        
        Paramters
        ---------
        
        =================  ==================  =======================  ===================================================================
        OMDb API Param     omdb.py Param       Value                    Description
        =================  ==================  =======================  ===================================================================
        ``s``              ``search``          string **(optional)**    title of media to search for
        ``i``              ``imdbid``          string **(optional)**    a valid IMDb ID
        ``t``              ``title``           string **(optional)**    title of media to return
        ``y``              ``year``            year **(optional)**      year of media
        ``page``           ``page``            page **(optional)**      page to return
        ``Season``         ``season``          season **(optional)**    season number
        ``Episode``        ``episode``         episode **(optional)**   episode number
        ``type``           ``media_type``      string **(optional)**    media type to return (one of ``movie``, ``episode``, or ``series``)
        ``plot=full``      ``fullplot=True``   ``full``                 include extended plot
        ``plot=short``     ``fullplot=False``  ``short``                include short plot **(default)**
        ``tomatoes=true``  ``tomatoes=True``   ``true`` **(optional)**  add Rotten Tomatoes data to response
        =================  ==================  =======================  ===================================================================
        
        **NOTE:** By default all ``OMDb API`` responses are formatted as ``JSON``. However, ``OMDb API`` also supports responses formatted as ``XML``. Since ``omdb.py`` will handle ``JSON`` to ``dict`` conversion automatically, it's generally not necessary (nor is it supported by the main ``ombd.py`` methods) to return ``XML`` formatted responses. But this can be accomplished by directly using ``omdb.request``:
        
        
        .. code-block:: python
        
        	import omdb
        
        	# must use OMDb API parameters
        	res = omdb.request(t='True Grit', y=1969, r='xml')
        	xml_content = res.content
        
        
        Methods
        -------
        
        All methods are accessible via:
        
        
        .. code-block:: python
        
        	import omdb
        
        	# omdb.<method>
        
        =====================================  =======================================================================================  ==========
        Method                                 Description                                                                              Returns
        =====================================  =======================================================================================  ==========
        ``get(**params)``                      Generic request to OMDb API (requires keyword argument passing of all parameters).       ``dict``
        ``search(search, **params)``           Search by string.                                                                        ``list``
        ``search_movie(search, **params)``     Search movies by string.                                                                 ``list``
        ``search_episode(search, **params)``   Search episodes by string.                                                               ``list``
        ``search_series(search, **params)``    Search series by string.                                                                 ``list``
        ``imdbid(imdbid, **params)``           Get by IMDB ID                                                                           ``dict``
        ``title(title, **params)``             Get by title                                                                             ``dict``
        ``set_default(key, default)``          Set default request parameter                                                            ``None``
        =====================================  =======================================================================================  ==========
        
        
        Client
        ------
        
        Instead of using the ``omdb`` module to access the OMDb API, one can create an ``OMDBClient`` instance:
        
        
        .. code-block:: python
        
            from omdb import OMDBClient
        
            client = OMDBClient(apikey=API_KEY)
        
        =============================  =========================================================================================  =========================
        Class Methods                  Description                                                                                Returns
        =============================  =========================================================================================  =========================
        ``get(**omdb_params)``         Generic request to OMDb API which can be used for any type of query.                       ``list`` or ``dict``
        ``request(**omdbapi_params)``  Lower-level request to OMDb API which accepts URL query parameters supported by OMDb API.  ``request.Response``
        ``set_default(key, default)``  Set default request parameter.                                                             ``None``
        =============================  =========================================================================================  =========================
        
        
        API Data
        --------
        
        API data returned from the ``OMDb API`` is returned as a dictionary with their fields converted from ``CamelCase`` to ``underscore_case``.
        
        
        Search Model Fields
        ~~~~~~~~~~~~~~~~~~~
        
        ==============  =============
        OMDb API Field  omdb.py Field
        ==============  =============
        ``Title``       ``title``
        ``Year``        ``year``
        ``Type``        ``type``
        ``imdbID``      ``imdb_id``
        ==============  =============
        
        
        Get Model Fields (tomatoes=False)
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        ==============  ===============
        OMDb API Field  omdb.py Field
        ==============  ===============
        ``Title``       ``title``
        ``Year``        ``year``
        ``Type``        ``type``
        ``Actors``      ``actors``
        ``Awards``      ``awards``
        ``Country``     ``country``
        ``Director``    ``director``
        ``Genre``       ``genre``
        ``Episode``     ``episode``
        ``Episodes``    ``episodes``
        ``Season``      ``season``
        ``SeriesID``    ``series_id``
        ``Language``    ``language``
        ``Metascore``   ``metascore``
        ``Plot``        ``plot``
        ``Poster``      ``poster``
        ``Rated``       ``rated``
        ``Ratings``     ``ratings``
        ``Released``    ``released``
        ``Response``    ``response``
        ``Runtime``     ``runtime``
        ``Writer``      ``writer``
        ``imdbID``      ``imdb_id``
        ``imdbRating``  ``imdb_rating``
        ``imdbVotes``   ``imdb_votes``
        ==============  ===============
        
        
        Get Model Fields (tomatoes=True)
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        =====================  =======================
        OMDb API Field         omdb.py Field
        =====================  =======================
        ``Title``              ``title``
        ``Year``               ``year``
        ``Type``               ``type``
        ``Actors``             ``actors``
        ``Awards``             ``awards``
        ``Country``            ``country``
        ``Director``           ``director``
        ``Genre``              ``genre``
        ``Episode``            ``episode``
        ``Season``             ``season``
        ``SeriesID``           ``series_id``
        ``Language``           ``language``
        ``Metascore``          ``metascore``
        ``Plot``               ``plot``
        ``Poster``             ``poster``
        ``Rated``              ``rated``
        ``Ratings``            ``ratings``
        ``Released``           ``released``
        ``Runtime``            ``runtime``
        ``Writer``             ``writer``
        ``imdbID``             ``imdb_id``
        ``imdbRating``         ``imdb_rating``
        ``imdbVotes``          ``imdb_votes``
        ``BoxOffice``          ``box_office``
        ``DVD``                ``dvd``
        ``Production``         ``production``
        ``Website``            ``website``
        ``tomatoConsensus``    ``tomato_consensus``
        ``tomatoFresh``        ``tomato_fresh``
        ``tomatoImage``        ``tomato_image``
        ``tomatoMeter``        ``tomato_meter``
        ``tomatoRating``       ``tomato_rating``
        ``tomatoReviews``      ``tomato_reviews``
        ``tomatoRotten``       ``tomato_rotten``
        ``tomatoUserMeter``    ``tomato_user_meter``
        ``tomatoUserRating``   ``tomato_user_rating``
        ``tomatoUserReviews``  ``tomato_user_reviews``
        =====================  =======================
        
        
        Usage
        =====
        
        
        General Import
        --------------
        
        
        .. code-block:: python
        
        	import omdb
        
        
        .. note::
        
            All functions below support a ``timeout`` keyword argument that will be forwarded to the underlying ``requests.get`` function call. You can also set a global default using ``omdb.set_default('timeout', <timeout>)`` that will be used when ``timeout`` is not explicitly provided.
        
        API Key
        -------
        
        Usage of the OMDb API currently requires an API key. Set the OMDb API key with ``omdb.set_default`` or when creating a new ``omdb.OMDBClient`` instance:
        
        .. code-block:: python
        
            # if using the module level client
            omdb.set_default('apikey', API_KEY)
        
            # if creating a new client instance
            client = omdb.OMDBClient(apikey=API_KEY)
        
        
        omdb.get()
        ----------
        
        
        .. code-block:: python
        
        	# include full plot and Rotten Tomatoes data
        	omdb.get(title='True Grit', year=1969, fullplot=True, tomatoes=True)
        
        	# set timeout of 5 seconds for this request
        	omdb.get(title='True Grit', year=1969, fullplot=True, tomatoes=True, timeout=5)
        
        
        omdb.search()
        -------------
        
        
        .. code-block:: python
        
        	# search by string
        	omdb.search('True Grit')
        	omdb.search('True Grit', timeout=5)
        	omdb.search('true', page=2)
        
        
        omdb.search_movie()
        -------------------
        
        
        .. code-block:: python
        
        	# search movies by string
        	omdb.search_movie('True Grit')
        	omdb.search_movie('True Grit', timeout=5)
        	omdb.search_movie('true', page=2)
        
        
        omdb.search_episode()
        ---------------------
        
        
        .. code-block:: python
        
        	# search episodes by string
        	omdb.search_episode('True Grit')
        	omdb.search_episode('True Grit', timeout=5)
        	omdb.search_episode('true', page=2)
        
        
        omdb.search_series()
        --------------------
        
        
        .. code-block:: python
        
        	# search series by string
        	omdb.search_series('True Grit')
        	omdb.search_series('True Grit', timeout=5)
        	omdb.search_series('true', page=2)
        
        
        omdb.imdbid()
        -------------
        
        
        .. code-block:: python
        
        	# get by IMDB id
        	omdb.imdbid('tt0065126')
        	omdb.imdbid('tt0065126', timeout=5)
        
        
        omdb.title()
        ------------
        
        
        .. code-block:: python
        
        	# get by title
        	omdb.title('True Grit')
        	omdb.title('True Grit', timeout=5)
        
        
        omdb.set_default()
        ------------------
        
        
        .. code-block:: python
        
        	# include tomatoes data by default
        	omdb.set_default('tomatoes', True)
        	omdb.title('True Grit') == omdb.title('True Grit', tomatoes=True)
        
        	# set a global timeout of 5 seconds for all HTTP requests
        	omdb.set_default('timeout', 5)
        
        
        omdb.request()
        --------------
        
        
        .. code-block:: python
        
        	# lower level API request
        	omdb.request(t='True Grit', y=1969, plot='full', tomatoes='true', timeout=5)
        
        
        **Returns:**
        
        A ``requests.Response`` object.
        
        
        Errors and Exceptions
        =====================
        
        Under the hood, ``omdb.py`` uses the `requests <http://www.python-requests.org/>`_ library. For a listing of explicit exceptions raised by ``requests``, see `Requests: Errors and Exceptions <http://www.python-requests.org/en/latest/user/quickstart/#errors-and-exceptions>`_.
        
        By default ``requests`` will not raise an ``Exception`` when an HTTP response's status code is not ``200``. However, ``omdb.py`` *WILL* raise an ``requests.exceptions.HTTPError`` error for any response with a non-200 status code.
        
        
        .. |version| image:: http://img.shields.io/pypi/v/omdb.svg?style=flat-square
            :target: https://pypi.python.org/pypi/omdb
        
        .. |travis| image:: http://img.shields.io/travis/dgilland/omdb.py/master.svg?style=flat-square
            :target: https://travis-ci.org/dgilland/omdb.py
        
        .. |coveralls| image:: http://img.shields.io/coveralls/dgilland/omdb.py/master.svg?style=flat-square
            :target: https://coveralls.io/r/dgilland/omdb.py
        
        .. |license| image:: http://img.shields.io/pypi/l/omdb.svg?style=flat-square
            :target: https://pypi.python.org/pypi/omdb
        
        
        Changelog
        =========
        
        
        v0.10.1 (2018-12-10)
        --------------------
        
        - Fix mishandling of ``fullplot``, ``tomatoes``, and ``timeout`` parameters in ``OMDBClient.get()`` that did not work correctly in conjuction with ``OMDBClient.set_default()``.
        - Fix mishandling of ``type`` parameter which was not being serialized to API request.
        
        
        v0.10.0 (2018-04-08)
        --------------------
        
        - Add methods to ``OMDBClient`` that mirror module functions:
        
          - ``search()``
          - ``search_movie()``
          - ``search_episode()``
          - ``search_series()``
          - ``imdbid()``
          - ``title()``
        
        
        v0.9.1 (2018-03-24)
        -------------------
        
        - Remove ``omdb.models`` module and return plain dictionaries from search results instead of custom model classes. (**breaking change**)
        
          - Previously, one could access result items using attributes (e.g. ``result.title``) or indexes (e.g. ``result['title']``). Now, results are ``dict`` objects so must use ``result['title']``.
        
        - Rename ``omdb.Client`` to ``omdb.OMDBClient``. (**breaking change**)
        - Make ``omdb.request|omdb.OMDBClient.request`` use an API key if it's set.
        
        
        v0.8.1 (2017-08-10)
        -------------------
        
        - Add support for OMDb API key via ``omdb.set_default(apikey=API_KEY)`` or ``client = omdb.Client(apikey=API_KEY)``. Thanks oshribr_!
        - Add ``Epiodes`` OMDb API fields as ``episodes`` model field.
        
        
        v0.7.0 (2016-08-03)
        -------------------
        
        - Add support for ``page`` parameter to ``search``. Thanks taserian_!
        
        
        v0.6.0 (2016-05-22)
        -------------------
        
        - Add support for ``timeout`` parameter to all HTTP requests.
        
        
        v0.5.0 (2015-07-29)
        -------------------
        
        - Add support for ``Season``/``Episode`` OMDb parameter via ``season``/``episode`` arguments to every main API function. Thanks cihansahin_!
        
        
        v0.4.0 (2015-04-29)
        -------------------
        
        - Add ``Season``, ``Episode``, and ``SeriesID`` OMDb API fields as ``season``, ``episode``, and ``series_id`` model fields.
        
        
        v0.3.1 (2015-01-27)
        -------------------
        
        - Add metadata to main module:
        
            - ``__title__``
            - ``__summary__``
            - ``__url__``
            - ``__version__``
            - ``__author__``
            - ``__email__``
            - ``__license__``
        
        
        v0.3.0 (2015-01-13)
        -------------------
        
        - Add ``search_movie``.
        - Add ``search_episode``.
        - Add ``search_series``.
        - Add support for ``type`` OMDb parameter via ``media_type`` argument to every main API function.
        
        
        v0.2.0 (2014-10-16)
        -------------------
        
        - Update ``models.Item`` with additional ``OMDb API`` fields: ``Awards``, ``Country``, ``Language``, and ``Metascore``.
        - Add ``omdb.request`` method for easier access to raw request response.
        - Initialization of ``omdb.Client`` now accepts keyword arguments for API request parameter defaults. Previously, a ``dict`` object needed to be passed in.
        - Full PEP8 compliance.
        - Integrate ``tox`` testing into ``setup.py``.
        
        
        v0.1.1 (2014-02-09)
        -------------------
        
        - Python3 support. Thanks agronholm_!
        - PEP8 compliance excluding max-line-length. Thanks agronholm_!
        - Wheel support. Thanks agronholm_!
        
        
        v0.1.0 (2013-11-24)
        -------------------
        
        - Convert API response to data models (see omdb/models.py).
        - Add /tests folder and move appropriate doctests there.
        - Return empty data for ``search`` and ``get`` requests which return no record(s).
        - Add ``omdb.set_default()`` for setting default request parameters (e.g. ``set_default(tomatoes=True)`` to always include tomatoes data)
        
        
        v0.0.1 (2013-11-12)
        -------------------
        
        - Initial release.
        
        
        .. _agronholm: https://github.com/agronholm
        .. _cihansahin: https://github.com/cihansahin
        .. _taserian: https://github.com/taserian
        .. _oshribr: https://github.com/oshribr
        
Keywords: omdb imdb movies
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
