omdb 0.9.1

Paramters

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:

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:

import omdb

# omdb.<method>

Client

Instead of using the omdb module to access the OMDb API, one can create an OMDBClient instance:

from omdb import OMDBClient

client = OMDBClient(apikey=API_KEY)

API Data

API data returned from the OMDb API is returned as a dictionary with their fields converted from CamelCase to underscore_case.

General Import

import omdb

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:

# 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()

# 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()

# search by string
omdb.search('True Grit')
omdb.search('True Grit', timeout=5)
omdb.search('true', page=2)

omdb.search_movie()

# 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()

# 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()

# search series by string
omdb.search_series('True Grit')
omdb.search_series('True Grit', timeout=5)
omdb.search_series('true', page=2)

omdb.imdbid()

# get by IMDB id
omdb.imdbid('tt0065126')
omdb.imdbid('tt0065126', timeout=5)

omdb.title()

# get by title
omdb.title('True Grit')
omdb.title('True Grit', timeout=5)

omdb.set_default()

# 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()

# lower level API request
omdb.request(t='True Grit', y=1969, plot='full', tomatoes='true', timeout=5)

Returns:

A requests.Response object.

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.