themoviedb

|Code Coverage| |PyPI Version| |Code style: black| |PyPI License|

themoviedb

A modern and easy to use API wrapper for The Movie Database (TMDb) API v3 written in Python. Supports sync and async requests!

.. image:: https://github.com/leandcesar/themoviedb/blob/master/docs/assets/themoviedb.gif?raw=true :target: https://github.com/leandcesar/themoviedb :alt: themoviedb

Overview

The themoviedb is a synchronous and asynchronous wrapper, written in Python, for The Movie Database (TMDb) API v3.

The Movie Database (TMDb) <https://www.themoviedb.org>__ is a community built movie and TV database.

The TMDb API <https://www.themoviedb.org/documentation/api>__ service is for those of you interested in using our movie, TV show or actor images and/or data in your application.

A TMDb user account <https://www.themoviedb.org/account/signup>__ is required to request an API key.

Getting started

Requirements

• python (Python >=3.8)
• pip (Python package manager)

Install

The easiest way to install themoviedb is via pip.

.. code-block:: shell

pip install themoviedb[full]

Or only the sync version (with requests).

.. code-block:: shell

pip install themoviedb[sync]

Or only the async version (with aiohttp).

.. code-block:: shell

pip install themoviedb[async]

API Key

You will need an API key to The Movie Database to access the API. To obtain a key, follow these steps:

1. Register <https://www.themoviedb.org/account/signup>__ for and verify an account.
2. Log <https://www.themoviedb.org/login>__ into your account.
3. Select the API section <https://www.themoviedb.org/settings/api>__ on left side of your account page.
4. Click on the link to generate a new API key and follow the instructions.

Usage

Sync mode

.. code:: python

from themoviedb import TMDb

Async mode

.. code:: python

from themoviedb import aioTMDb

Configuration

Initialize a TMDb object and set your API Key, language and region.

.. code:: python

tmdb = TMDb(key="YOUR_API_KEY", language="pt-BR", region="BR")
# or: tmdb = aioTMDb(key="YOUR_API_KEY", language="pt-BR", region="BR")

Alternatively, set after initialize.

.. code:: python

tmdb = TMDb()
# or: tmdb = aioTMDb()
tmdb.key = "YOUR_API_KEY"
tmdb.language = "pt-BR"     # default: en-US
tmdb.region = "BR"          # default: US

Alternatively too, you can export your API key, language and region logger as an environment variable.

.. code:: bash

$ export TMDB_KEY="YOUR_API_KEY"
$ export TMDB_LANGUAGE="pt-BR"  # ISO 639-1
$ export TMDB_REGION="BR"       # ISO-3166-1

And then you will no longer need to set your API key, language and region.

.. code:: python

tmdb = TMDb()   # from env: TMDB_KEY="YOUR_API_KEY", TMDB_LANGUAGE="pt-BR", TMDB_REGION="BR"
# or: tmdb = aioTMDb()

Examples

Get the list of top rated movies (sync mode).

.. code:: python

from themoviedb import TMDb

tmdb = TMDb()
movies = tmdb.movies().top_rated()
for movie in movies:
    print(movie)

Get the list of popular TV shows (async mode).

.. code:: python

import asyncio
from themoviedb import aioTMDb

async def main():
    tmdb = aioTMDb()
    movies = await tmdb.tvs().popular()
    for movie in movies:
        print(movie)

asyncio.run(main())

Discover movies by different types of data.

.. code:: python

from themoviedb import TMDb

tmdb = TMDb()
movies = tmdb.discover().movie(
    sort_by="vote_average.desc",
    primary_release_date__gte="1997-08-15",
    vote_count__gte=10000,
    vote_average__gte=6.0,
)
for movie in movies:
    print(movie)

Get the details of movie for a search.

.. code:: python

import asyncio
from themoviedb import aioTMDb

async def main():
    tmdb = aioTMDb()
    movies = await tmdb.search().movies("fight club")
    movie_id = movies[0].id  # get first result
    movie = await tmdb.movie(movie_id).details(append_to_response="credits,external_ids,images,videos")
    print(movie.title, movie.year)
    print(movie.tagline)
    print(movie.poster_url)
    print(movie.external_ids.imdb_url)
    for person in movie.credits.cast:
        print(person.name, person.character)

asyncio.run(main())

.. |Code Coverage| image:: https://codecov.io/gh/leandcesar/themoviedb/branch/master/graph/badge.svg?token=OOILIE0RTS :target: https://codecov.io/gh/leandcesar/themoviedb .. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/psf/black .. |PyPI Version| image:: https://img.shields.io/pypi/v/themoviedb?color=blue :target: https://pypi.org/project/themoviedb/ .. |PyPI License| image:: https://img.shields.io/pypi/l/themoviedb.svg :target: https://img.shields.io/pypi/l/themoviedb.svg