Metadata-Version: 1.1
Name: omdb
Version: 0.2.0
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``:
        
        .. code-block::
        
        	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
        ``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).       ``Item``
        ``search(search, **params)``   Search by string.                                                                        ``Search``
        ``imdbid(imdbid, **params)``   Get by IMDB ID                                                                           ``Item``
        ``title(title, **params)``     Get by title                                                                             ``Item``
        ``set_default(key, default)``  Set default request parameter                                                            ``None``
        =============================  =======================================================================================  ==========
        
        
        Client
        ------
        
        While generally not necessary, one can use the lower level ``OMDb API Client`` for accessing the API:
        
        
        .. code-block:: python
        
        	from omdb import Client
        
            client = Client()
        
        =============================  =========================================================================================  =========================
        Class Methods                  Description                                                                                Returns
        =============================  =========================================================================================  =========================
        ``get(**omdb_params)``         Generic request to OMDb API which can be used for any type of query.                       ``Search`` or ``GetItem``
        ``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``
        =============================  =========================================================================================  =========================
        
        
        Models
        ------
        
        Movie data returned from the ``OMDb API`` is converted to a custom dict subclass which allows both ``data['key']`` and ``data.key`` access.
        
        There are two main models:
        
        - ``omdb.models.Search`` (a list of ``Item`` instances)
        - ``omdb.models.Item``
        
        Which can be accessed like the following:
        
        
        .. code-block:: python
        
        	import omdb
        
        	movie = omdb.title('True Grit')
        	movie.title == 'True Grit'
        	movie['title'] == 'True Grit'
        
        	search = omdb.search('True Grit')
        	search[0].title == 'True Grit'
        
        
        All fields from the ``OMDb API`` are converted from ``CamelCaseFields`` to ``underscore_fields``:
        
        
        Search Item Fields
        ~~~~~~~~~~~~~~~~~~
        
        ==============  =============
        OMDb API Field  omdb.py Field
        ==============  =============
        ``Title``       ``title``
        ``Year``        ``year``
        ``Type``        ``type``
        ``imdbID``      ``imdb_id``
        ==============  =============
        
        
        Get Item 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``
        ``Language``    ``language``
        ``Metascore``   ``metascore``
        ``Plot``        ``plot``
        ``Poster``      ``poster``
        ``Rated``       ``rated``
        ``Released``    ``released``
        ``Response``    ``response``
        ``Runtime``     ``runtime``
        ``Writer``      ``writer``
        ``imdbID``      ``imdb_id``
        ``imdbRating``  ``imdb_rating``
        ``imdbVotes``   ``imdb_votes``
        ==============  =============
        
        
        Get Item 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``
        ``Language``           ``language``
        ``Metascore``          ``metascore``
        ``Plot``               ``plot``
        ``Poster``             ``poster``
        ``Rated``              ``rated``
        ``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
        
        
        omdb.get()
        ----------
        
        
        .. code-block:: python
        
        	# include full plot and Rotten Tomatoes data
        	omdb.get(title='True Grit', year=1969, fullplot=True, tomatoes=True)
        
        
        omdb.search()
        -------------
        
        
        .. code-block:: python
        
        	# search by string
        	omdb.search('True Grit')
        
        
        omdb.imdbid()
        -------------
        
        
        .. code-block:: python
        
        	# get by IMDB id
        	omdb.imdbid('tt0065126')
        
        
        omdb.title()
        ------------
        
        
        .. code-block:: python
        
        	# get by title
        	omdb.title('True Grit')
        
        
        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)
        
        
        omdb.request()
        --------------
        
        
        .. code-block:: python
        
        	# lower level API request
        	omdb.request(t='True Grit', y=1969, plot='full', tomatoes='true')
        
        
        **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 `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.
        
        
        LICENSE
        =======
        
        This software is licensed under the MIT License.
        
        
        .. |version| image:: http://img.shields.io/pypi/v/omdb.svg?style=flat
            :target: https://pypi.python.org/pypi/omdb.py/
        
        .. |travis| image:: http://img.shields.io/travis/dgilland/omdb.py/master.svg?style=flat
            :target: https://travis-ci.org/dgilland/omdb.py
        
        .. |coveralls| image:: http://img.shields.io/coveralls/dgilland/omdb.py/master.svg?style=flat
            :target: https://coveralls.io/r/dgilland/omdb.py
        
        .. |license| image:: http://img.shields.io/pypi/l/omdb.svg?style=flat
            :target: https://pypi.python.org/pypi/omdb.py/
        
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.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
