imdbpie 5.4.4

ImdbPie
=======

|PyPI| |Python Versions| |Build Status|

Python IMDB client using the IMDB JSON web service made available for their iOS application.

API Terminology
---------------

- ``Title`` this can be a movie, tv show, video, documentary etc.
- ``Name`` this can be a credit, cast member, any person generally.

Installation
------------

To install imdbpie, simply:

.. code:: bash

pip install imdbpie

How To Use
----------

Initialise the client
~~~~~~~~~~~~~~~~~~~~~

.. code:: python

from imdbpie import Imdb
imdb = Imdb()

Available methods
~~~~~~~~~~~~~~~~~

NOTE: For each client method, if the resource cannot be found they will
raise ``LookupError``, for any other API status codes > 399 the client will raise ``ImdbAPIError``.

+----------------------------------------------------------------+-----------------------------------+
| Example | Description |
+================================================================+===================================+
| ``get_title('tt0111161')`` | Returns a dict containing title |
| | information |
+----------------------------------------------------------------+-----------------------------------+
| ``search_for_title("The Dark Knight")`` | Returns a dict of results |
| | |
+----------------------------------------------------------------+-----------------------------------+
| ``search_for_name("Christian Bale")`` | Returns a dict of results |
| | |
+----------------------------------------------------------------+-----------------------------------+
| ``title_exists('tt0111161')`` | Returns True if exists otherwise |
| | False |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_genres('tt0303461')`` | Returns a dict containing title |
| | genres information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_credits('tt0303461')`` | Returns a dict containing title |
| | credits information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_quotes('tt0303461')`` | Returns a dict containing title |
| | quotes information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_ratings('tt0303461')`` | Returns a dict containing title |
| | ratings information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_connections('tt0303461')`` | Returns a dict containing title |
| | connections information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_similarities('tt0303461')`` | Returns a dict containing title |
| | similarities information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_videos('tt0303461')`` | Returns a dict containing title |
| | videos information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_news('tt0303461')`` | Returns a dict containing news |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_trivia('tt0303461')`` | Returns a dict containing trivia |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_soundtracks('tt0303461')`` | Returns a dict containing |
| | soundtracks information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_goofs('tt0303461')`` | Returns a dict containing “goofs” |
| | and teaser information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_technical('tt0303461')`` | Returns a dict containing |
| | technical information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_companies('tt0303461')`` | Returns a dict containing |
| | information about companies |
| | related to title |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_episodes('tt0303461')`` | Returns a dict containing season |
| | and episodes information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_episodes_detailed(imdb_id='tt0303461', season=1)`` | Returns a dict containing |
| | detailed season episodes |
| | information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_top_crew('tt0303461')`` | Returns a dict containing |
| | detailed information about |
| | title’s top crew (ie: directors, |
| | writters, etc.) |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_plot('tt0111161')`` | Returns a dict containing title |
| | plot information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_plot_synopsis('tt0111161')`` | Returns a dict containing title |
| | plot synopsis information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_awards('tt0111161')`` | Returns a dict containing title |
| | plot information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_releases('tt0111161')`` | Returns a dict containing |
| | releases information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_versions('tt0111161')`` | Returns a dict containing |
| | versions information (meaning |
| | different versions of this title |
| | for different regions, or |
| | different versions for DVD vs |
| | Cinema) |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_user_reviews('tt0111161')`` | Returns a dict containing user |
| | review information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_metacritic_reviews('tt0111161')`` | Returns a dict containing |
| | metacritic review information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_title_images('tt0111161')`` | Returns a dict containing title |
| | images information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_name('nm0000151')`` | Returns a dict containing |
| | person/name information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_name_filmography('nm0000151')`` | Returns a dict containing |
| | person/name filmography |
| | information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_name_images('nm0000032')`` | Returns a dict containing |
| | person/name images information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_name_videos('nm0000032')`` | Returns a dict containing |
| | person/name videos information |
+----------------------------------------------------------------+-----------------------------------+
| ``validate_imdb_id('tt0111161')`` | Raises ``ValueError`` if not |
| | valid |
+----------------------------------------------------------------+-----------------------------------+
| ``get_popular_titles()`` | Returns a dict containing popular |
| | titles information |
+----------------------------------------------------------------+-----------------------------------+
| ``get_popular_shows()`` | Returns a dict containing popular |
| | tv shows |
+----------------------------------------------------------------+-----------------------------------+
| ``get_popular_movies()`` | Returns a dict containing popular |
| | movies |
+----------------------------------------------------------------+-----------------------------------+

Requirements
------------

::

1. Python 2 or 3
2. See requirements.txt

Running the tests
-----------------

.. code:: bash

pip install -r test_requirements.txt
py.test src/tests

.. |PyPI| image:: https://img.shields.io/pypi/v/imdbpie.svg
:target: https://pypi.python.org/pypi/imdb-pie
.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/imdbpie.svg
:target: https://pypi.python.org/pypi/imdb-pie
.. |Build Status| image:: https://travis-ci.org/richardasaurus/imdb-pie.png?branch=master
:target: https://travis-ci.org/richardasaurus/imdb-pie


.. :changelog:

Release History
---------------

5.4.4 (2018-04-17)
++++++++++++++++++

- Python 2.x setup.py bugfix.
- Bugfix for ``title_exists`` method returning ``None``.
- Bugfix for ``get_title`` raising an incorrect exception when redirection title.


5.4.3 (2018-04-05)
++++++++++++++++++

- Updates license.


5.4.2 (2018-04-05)
++++++++++++++++++

- Fixes missing setuptools dependency for pypi display of markdown formatted files.


5.4.1 (2018-04-05)
++++++++++++++++++

- Packaging documentation fixes.


5.4.0 (2018-03-18)
++++++++++++++++++

- Bugfix for incorrect AttributeError message showing when undefined attrs called on client class.
- Adds ``get_title_top_crew`` method.


5.3.0 (2018-02-27)
++++++++++++++++++

- Adds ``get_title_plot_taglines`` method.
- Adds ``get_title_news`` method.
- Adds ``get_title_trivia`` method.
- Adds ``get_title_soundtracks`` method.
- Adds ``get_title_goofs`` method.
- Adds ``get_title_technical`` method.
- Adds ``get_title_companies`` method.
- Adds ``get_title_episodes_detailed`` method.


5.2.0 (2018-01-11)
++++++++++++++++++

- Updates ``get_title`` to call "/auxiliary" as "/fulldetails" endpoint now returns an error.
- Adds ``get_title_quotes`` method.
- Adds ``get_title_ratings`` method.
- Adds ``get_title_connections`` method.
- Adds ``get_title_awards`` method.
- Adds ``get_title_plot_synopsis`` method.
- Adds ``get_title_versions`` method.
- Adds ``get_title_releases`` method.
- Adds ``get_title_similarities`` method.
- Adds ``get_title_videos`` method.
- Adds ``get_name_videos`` method.
- Adds ``get_name_filmography`` method.
- Adds response status code to ``ImdbAPIError`` exception message.


5.1.0 (2018-01-10)
++++++++++++++++++

- Adds ``get_title_genres`` method.


5.0.0 (2018-01-10)
++++++++++++++++++

- Fixes client to work with new API.
- Renames most of methods on ``Imdb`` class.
- Changes all methods on ``Imdb`` to return raw JSON resource dictionary rather than Python objects.
- Removes params from ``Imdb`` ``__init__`` method (user_agent, proxy_uri, verify_ssl, api_key, cache, anonymize).
- Adds ``clear_cached_credentials`` method to ``Imdb`` class.


4.4.2 (2018-01-03)
++++++++++++++++++

- Fixes bug when searching with non alphanumeric characters, second attempt.


4.4.1 (2017-12-27)
++++++++++++++++++

- Fixes bug when searching with non alphanumeric characters.


4.4.0 (2017-12-24)
++++++++++++++++++

- Fixes ``search_for_person`` and ``search_for_title`` methods, which were broken because XML api used by the client was removed, migrated to using search suggestions api used by the website itself.
- Adds optional ``session`` param to client init method, used to specify ``requests.Session``.
- All client methods will raise ``ValueError`` if invalid ``imdb_id`` param given.


4.3.0 (2017-08-10)
++++++++++++++++++

**Added**

- Added ``Imdb.popular_movies`` to retrieve current popular movies.


4.2.0 (2016-09-29)
++++++++++++++++++

**Added**

- ``Person.photo_url`` has been added. It returns a string (url) or None.


4.1.0 (2016-07-26)
++++++++++++++++++

- Changed ``Title`` and other objects to use less memory.
- Added notice of deprecation of caching in version 5.0.0.
- Added ``Imdb.get_episodes`` to retrieve Title Episode information.


4.0.2 (2015-08-08)
++++++++++++++++++

**Added**
- Added ``cache_expiry`` parameter to ``Imdb`` class, to specify cache expiry in seconds.

**Changes**

- Internal caching changed you use 3rd party package ``cachecontrol``.

**Removed**

- ``Imdb`` class no longer takes a ``cache_dir`` parameter.


3.0.0 (2015-06-12)
++++++++++++++++++

**Changed**

- All methods on ``Imdb`` will raise ``imdbpie.exceptions.HTTPError`` if a bad request to the API or resource is not found ("Errors should never pass silently").
- ``Imdb.get_title_reviews`` now has param `max_results` to limit number of reviews returned.


2.1.0 (2015-05-03)
++++++++++++++++++
**Added**
- Added verify_ssl kwarg option to ``Imdb`` object. Allows for controlling of ssl cert verification on all requests made.


2.0.1 (2015-03-30)
++++++++++++++++++
**Added**

- ``Title.plot_outline`` has been added. It returns a string.


2.0.0 (2015-03-12)
++++++++++++++++++
**Added**

- ``Imdb.search_for_person`` has been added. It returns a list of dicts.
- ``Imdb.get_title_plots`` has been added. It returns a list of strings.
- ``Title.trailer_image_urls`` returns a list of trailer urls (string).
- ``Imdb.get_person_by_id`` has been added. It returns a Person object.

**Changed**

- ``Title.plots`` returns a list of *full* plots.
- ``Title.trailers`` returns a list of dicts (keys: "url", "format").
- ``Title.runtime`` returns runtime in seconds now instead of hours.
- ``Person.role`` is now ``Person.roles`` and returns a list rather than a string.
- ``Imdb.person_images`` has been renamed to ``Imdb.get_person_images``.
- ``Imdb.title_reviews`` has been renamed to ``Imdb.get_title_reviews`` and parameter ``limit`` has also been removed.
- ``Imdb.title_images`` has been renamed to ``Imdb.get_title_images``.
- ``Imdb.find_by_title`` has been renamed to ``Imdb.search_for_title``.
- ``Imdb.find_movie_by_id`` has been renamed to ``Imdb.get_title_by_id`` and parameter ``json`` has been removed.
- ``Imdb.movie_exists`` has been renamed to ``Imdb.title_exists``.

**Removed**

- ``Imdb.validate_id`` has been removed.
- ``Title.plot_outline`` has been removed.
- ``Title.trailer_img_url`` has been removed.

1.5.6 (2014-12-07)
++++++++++++++++++

- No notes, release made before changelog inception.