aio-tmdb 0.1.3
Asynchronous Python library for The Movie Database (TMDB) API v3
License: MIT
Keywords: movie,movies,tv,tv show,tv shows,tmdb,themoviedb,moviedb,movie database,api,wrapper

.. image:: https://raw.githubusercontent.com/leandcesar/aiotmdb/main/docs/images/logo.png
   :target: https://pypi.org/project/aio-tmdb/
   :align: center
   :alt: aiotmdb


--------------

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

**aiotmdb**, an async Python library for TMDB API.

-  `Overview <#overview>`__
-  `Getting started <#getting-started>`__
-  `Examples <#examples>`__
-  `Configuration <#configuration>`__

--------------

Overview
========

The **aiotmdb** is an 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.

To view all the methods available, you should head over to `TMDB API
Documentation <https://developers.themoviedb.org/3>`__.

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

Getting started
===============

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

-  ``python`` (Python 3.7 up to 3.9 supported)
-  ``pip`` (Python package manager)
-  ``aiohttp`` (Asynchronous HTTP Client/Server for Python)

Install
-------

The easiest way to install aiotmdb is via ``pip``.

::

    pip install aio-tmdb

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

The first step is to initialize a TMDB object and set your API Key.

.. code:: py

    import asyncio
    from aiotmdb import TMDB, Base, Search


    async def main():
        base = Base()
        base.key = "YOUR_API_KEY"
        search = Search()  # or TMDB.search()
        results = await search.movies("fight club")  
        for result in results:
            print(result.title)


    # Python 3.7+
    asyncio.run(main())

Alternatively, you can export your API key as an environment variable.

.. code:: bash

    $ export TMDB_KEY="YOUR_API_KEY"

And then you will no longer need to set your API key.

.. code:: py

    import asyncio
    from aiotmdb import TMDB, Movie


    async def main():
        # implicit env var: TMDB_KEY="YOUR_API_KEY"
        movie =  TMDB.movie()  # or Movie()
        results = await movie.popular()
        for result in results:
            print(result.title)


    asyncio.run(main())

Examples
========

Search
------

Search for companies, collections, keywords, movies, people and TV
shows.

.. code:: py

    from aiotmdb import TMDB, Search


    async def main():
        search = TMDB.search()  # or Search()

        # Movies
        for movie in await search.movies("potter", page=2, include_adult=True):
            print(f"[{movie.id}] {movie.title}, {movie.release_date}")

        # TV shows
        for tv_show in await search.tv_shows("bad", first_air_date_year=2008):
            print(f"[{tv_show.id}] {tv_show.name}, {tv_show.first_air_date}")

        # People
        for person in await search.person("chris"):
            known_for = person.known_for[0].get("title", "name")  # movie or TV show
            print(f"[{person.id}] {person.name} ({known_for})")

        # Movies, or TV shows, or people
        for result in await search.multi("anne"):
            name = result.get("title") or result.get("name")
            print(f"[{result.id}] {name}")


    asyncio.run(main())

Configuration
=============

Initialize a TMDB object and set your API Key, language, region and
debug logger.

.. code:: py

    from aiotmdb import TMDB, Base


    async def main():
        base = Base()
        base.key = "YOUR_API_KEY"
        base.debug = 1
        base.language = "pt-BR"
        base.region = "BR"

        watch_provider = TMDB.watch_provider()
        watch_providers = await watch_provider.movies()

Alternatively, you can export your API key, language, region and debug
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
    $ export TMDB_DEBUG=1

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

.. code:: py

    async def main():
        # implicit env vars: TMDB_KEY="YOUR_API_KEY" TMDB_LANGUAGE="pt-BR" TMDB_REGION="BR" TMDB_DEBUG=1
        watch_provider = TMDB.watch_provider()
        watch_providers = await watch_provider.movies()

You also can set language and region on object instantiation.

.. code:: py

    async def main():
        # implicit env vars: TMDB_KEY="YOUR_API_KEY" TMDB_LANGUAGE="pt-BR" TMDB_REGION="BR" TMDB_DEBUG=1
        discover = TMDB.discover()
        tv_shows = await discover.tv_shows()  # discover with the BR regional release date

        discover = TMDB.discover(language="en-US", region="US")
        tv_shows = await discover.tv_shows()  # discover with the US regional release date

.. |aiotmdb| image:: https://raw.githubusercontent.com/leandcesar/aiotmdb/bd5ad91d1c5bc0de31470926375677fec0484ba0/docs/images/logo.svg
   :target: https://pypi.org/project/aio-tmdb/
.. |PyPI Version| image:: https://img.shields.io/pypi/v/aiotmdb?color=blue
   :target: https://pypi.org/project/aio-tmdb/
.. |PyPI License| image:: https://img.shields.io/pypi/l/aiotmdb.svg
   :target: https://img.shields.io/pypi/l/aiotmdb.svg
.. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :target: https://github.com/psf/black