pyomdbapi API

The API for the pyomdbapi project

OMDB

class omdb.OMDB(api_key: str, timeout: float = 5.0, strict: bool = True)[source]

The OMDB API wrapper instance

Parameters:

  • api_key (str) – The API Key to use for the requests

  • timeout (float) – The timeout, in seconds

  • strict (bool) – To use strict error checking or not; strict (True) will throw errors if the API returns an error code, non-strict will not

Returns:

An OMDB API wrapper connection object

Return type:

OMDB

Note

With strict disabled, it is up to the user to check for and handle errors

property api_key: str

The API Key to use to connect to the OMDB API

Type:

str

close()[source]

Close the requests connection if necessary

get(*, title: str | None = None, imdbid: str | None = None, **kwargs) → Dict[source]

Retrieve a specific movie, series, or episode

Parameters:

  • title (str) – The title of the movie, series, or episode to return

  • imdbid (str) – The IMDB Id to use to pull the result

  • kwargs (dict) – the kwargs to add additional parameters to the API request

Returns:

A dictionary of all the results

Return type:

dict

Raises:

OMDBException – Raised when both title or imdbid is not provided

Note

Either title or imdbid is required

get_episode(*, title: str | None = None, imdbid: str | None = None, season: int = 1, episode: int | None = 1, **kwargs) → Dict[source]

Retrieve a TV series episode by title or IMDB id and season and episode number

Parameters:

  • title (str) – The name of the TV series to retrieve

  • imdbid (str) – The IMDB id of the TV series to retrieve

  • season (int) – The season number of the episode to retrieve

  • episode (int) – The episode number (based on season) of the episode to retrieve

  • kwargs (dict) – the kwargs to add additional parameters to the API request

Returns:

A dictionary of all the results

Return type:

dict

Note

Either title or imdbid is required

get_episodes(*, title: str | None = None, imdbid: str | None = None, season: int = 1, **kwargs) → Dict[source]

Retrieve all episodes of a TV series by season number

Parameters:

  • title (str) – The name of the TV series to retrieve

  • imdbid (str) – The IMDB id of the movie to retrieve

  • season (int) – The season number of the episode to retrieve

  • kwargs (dict) – the kwargs to add additional parameters to the API request

Returns:

A dictionary of all the results

Return type:

dict

Note

Either title or imdbid is required

get_movie(*, title: str | None = None, imdbid: str | None = None, **kwargs) → Dict[source]

Retrieve a movie by title or IMDB id

Parameters:

  • title (str) – The name of the movie to retrieve

  • imdbid (str) – The IMDB id of the movie to retrieve

  • kwargs (dict) – the kwargs to add additional parameters to the API request

Returns:

A dictionary of all the results

Return type:

dict

Note

Either title or imdbid is required

get_series(*, title: str | None = None, imdbid: str | None = None, pull_episodes: bool = False, **kwargs) → Dict[source]

Retrieve a TV series information by title or IMDB id

Parameters:

  • title (str) – The name of the TV series to retrieve

  • imdbid (str) – The IMDB id of the TV series to retrieve

  • pull_episodes (bool) – True to pull the episodes

  • kwargs (dict) – the kwargs to add additional parameters to the API request

Returns:

A dictionary of all the results

Return type:

dict

Note

Either title or imdbid is required

search(title: str, pull_all_results: bool = True, page: int = 1, **kwargs) → Dict[source]

Perform a search based on title

Parameters:

  • title (str) – The query string to lookup

  • page (int) – The page of results to return

  • pull_all_results (bool) – True to return all results; False to pull page only

  • kwargs (dict) – the kwargs to add additional parameters to the API request

Returns:

A dictionary of all the results

Return type:

dict

Note

If pull_all_results is True then page is ignored

search_movie(title: str, pull_all_results: bool = True, page: int = 1, **kwargs)[source]

Search for a movie by title

Parameters:

  • title (str) – The name, or part of a name, of the movie to look up

  • pull_all_results (bool) – True to return all results; False to pull page only

  • page (int) – The page of results to return

  • kwargs (dict) – the kwargs to add additional parameters to the API request

Returns:

A dictionary of all the results

Return type:

dict

search_series(title: str, pull_all_results: bool = True, page: int = 1, **kwargs) → Dict[source]

Search for a TV series by title

Parameters:

  • title (str) – The name, or part of a name, of the TV series to look up

  • pull_all_results (bool) – True to return all results; False to pull page only

  • page (int) – The page of results to return

  • kwargs (dict) – the kwargs to add additional parameters to the API request

Returns:

A dictionary of all the results

Return type:

dict

property strict: bool

Whether to throw or swallow errors; True will throw exceptions

Type:

bool

property timeout: float

The timeout parameter to pass to requests for how long to wait

Type:

float

Exceptions

Exceptions for the pyomdbapi project

exception omdb.exceptions.OMDBException(message: str)[source]

Base OMDB Exception

Parameters:

message (str) – The exception message

property message: str

The exception message

Type:

str

exception omdb.exceptions.OMDBInvalidAPIKey(api_key: str)[source]

Invalide API Key provided

Parameters:

api_key (str) – The API Key used that generated the exception

property api_key: str

The exception message

Type:

str

exception omdb.exceptions.OMDBLimitReached(api_key: str)[source]

Reached the limit of requests for the user - API Key combination

Parameters:

api_key (str) – The API Key used when connecting to the OMDB API service

property api_key: str

The OMDB API API key used

Type:

str

exception omdb.exceptions.OMDBNoResults(error: str, params: Dict)[source]

A No results returned exception

Parameters:

  • error (str) – The error message returned by the OMDB API service

  • params (dict) – The parameters used when the exception was raised

property error: str

The OMDB API exception message

Type:

str

property params: Dict

The parameters used when the exception was raised

Type:

dict

exception omdb.exceptions.OMDBTooManyResults(error: str, params: Dict)[source]

Too many results would be returned (per the OMDB API)

Parameters:

  • error (str) – The error message returned by the OMDB API service

  • params (dict) – The parameters used when the exception was raised

property error: str

The OMDB API exception message

Type:

str

property params: Dict

The parameters used when the exception was raised

Type:

dict

Utilities

A utilitites suite

omdb.utilities.camelcase_to_snake_case(_input: str) → str[source]

Convert a camel case string to a snake case string: CamelCase -> camel_case

Parameters:

_input (str) – The string to convert

omdb.utilities.range_inclusive(start: int, end: int, step: int = 1)[source]

Return the range of elements inclusive of the end value

Parameters:

  • start (int) – The start value of the range

  • end (int) – The end value of the range

  • step (int) – The step value to use

Yields:

int – The current value within the range

omdb.utilities.to_int(val: str) → int[source]

Turn the passed in variable into an int; returns 0 if errors

Parameters:

val (str) – The variable to turn into an int

Returns:

The int value if possible, 0 if an error occurs

Return type:

int