omdb 0.10.1
Python wrapper for OMDb API: http://www.omdbapi.com/
License: MIT License
Keywords: omdb imdb movies

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