Metadata-Version: 2.4
Name: tmdbv3api
Version: 1.10.0
Summary: A lightweight Python library for The Movie Database (TMDb) API.
Home-page: https://github.com/AnthonyBloomer/tmdbv3api
Author: Anthony Bloomer
Author-email: ant0@protonmail.ch
License: MIT
Keywords: movie,tvmovie database,tmdb,wrapper,database,themoviedb,moviedb,api
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Dist: requests
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: requires-dist
Dynamic: summary

tmdbv3api
=========

.. image:: https://travis-ci.org/AnthonyBloomer/tmdbv3api.svg?branch=master
    :target: https://travis-ci.org/AnthonyBloomer/tmdbv3api
    :alt: Build Status

.. image:: https://codecov.io/gh/AnthonyBloomer/tmdbv3api/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/AnthonyBloomer/tmdbv3api
    :alt: codecov

.. image:: https://img.shields.io/github/v/release/AnthonyBloomer/tmdbv3api
    :target: https://github.com/AnthonyBloomer/tmdbv3api/releases
    :alt: GitHub release (latest by date)

.. image:: https://img.shields.io/pypi/v/tmdbv3api
    :target: https://pypi.org/project/tmdbv3api/
    :alt: PyPI

.. image:: https://img.shields.io/pypi/dm/tmdbv3api.svg
    :target: https://pypi.org/project/tmdbv3api/
    :alt: Downloads

.. image:: https://img.shields.io/github/commits-since/AnthonyBloomer/tmdbv3api/latest
    :target: https://github.com/AnthonyBloomer/tmdbv3api/commits/master
    :alt: GitHub commits since latest release (by date) for a branch

A lightweight Python library for The Movie Database (TMDb) API. The TMDb API is a resource for developers to integrate movie, TV show and cast data along with posters or movie fan art. themoviedb.org is a free and community edited database.

Register an account: https://www.themoviedb.org/account/signup

Check out the API documentation: https://developers.themoviedb.org/3/getting-started/introduction

Install
~~~~~~~

tmdbv3api is available on the Python Package Index (PyPI) at
https://pypi.python.org/pypi/tmdbv3api

You can install tmdbv3api using pip.

::

    $ pip install tmdbv3api

Usage
~~~~~

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

.. code:: python

    from tmdbv3api import TMDb
    tmdb = TMDb()
    tmdb.api_key = 'YOUR_API_KEY'

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

.. code:: bash

    $ export TMDB_API_KEY='YOUR_API_KEY'

Other configuration settings include defining your ``language`` and enabling ``debug`` mode, for example:

.. code:: python

    tmdb.language = 'en'
    tmdb.debug = True

Then to communicate with TMDb, create an instance of one of the objects
and call that instances methods. For example, to retrieve movie
recommendations for a given movie id:

.. code:: python

    from tmdbv3api import Movie

    movie = Movie()

    recommendations = movie.recommendations(movie_id=111)

    for recommendation in recommendations:
        print(recommendation.title)
        print(recommendation.overview)

Examples
~~~~~~~~

Get the list of popular movies on The Movie Database. This list
refreshes every day.

.. code:: python


    movie = Movie()
    popular = movie.popular()

    for p in popular:
        print(p.id)
        print(p.title)
        print(p.overview)
        print(p.poster_path)


Get the primary information about a movie.

.. code:: python

    m = movie.details(343611)

    print(m.title)
    print(m.overview)
    print(m.popularity)

Search for movies by title.

.. code:: python

    from tmdbv3api import Search

    search = Search()
    results = search.movies('Mad Max')

    for res in results:
        print(res.id)
        print(res.title)
        print(res.overview)
        print(res.poster_path)
        print(res.vote_average)

Search terms and filters are passed as arguments, not as a dictionary:

.. code:: python

    results = search.movies('Matrix', year=1999)   # correct
    results = search.movies({'query': 'Matrix'})   # TypeError

If nothing matches, the results are empty rather than an error:

.. code:: python

    results = search.movies('something not found')
    len(results)        # 0
    list(results)       # []

Get the similar movies for a specific movie id.

.. code:: python

    similar = movie.similar(777)

    for result in similar:
        print(result.title)
        print(result.overview)

Search for TV shows by title.

.. code:: python

    tv = TV()
    show = tv.search('Breaking Bad')

    for result in show:
        print(result.name)
        print(result.overview)

Get the similar TV shows for a specific tv id.

.. code:: python

    similar = tv.similar(1396)

    for show in similar:
        print(show.name)
        print(show.overview)

Get the details of TV season for a specific tv id.

.. code:: python

    season = Season()
    show_season = season.details(1396, 1)
    print(show_season.air_date)
    print(len(show_season.episodes))

Get the general person information for a specific id.

.. code:: python

    person = Person()
    p = person.details(12)

    print(p.name)
    print(p.biography)

Discover movies by different types of data like average rating, number
of votes, genres and certifications.

.. code:: python


    # What movies are in theatres?

    discover = Discover()
    movie = discover.discover_movies({
        'primary_release_date.gte': '2017-01-20',
        'primary_release_date.lte': '2017-01-25'
    })

    # What are the most popular movies?

    movie = discover.discover_movies({
        'sort_by': 'popularity.desc'
    })

    # What are the most popular kids movies?

    movie = discover.discover_movies({
        'certification_country': 'US',
        'certification.lte': 'G',
        'sort_by': 'popularity.desc'
    })

Discover TV shows by different types of data like average rating, number
of votes, genres, the network they aired on and air dates.

.. code:: python

    # What are the most popular TV shows?

    show = discover.discover_tv_shows({
        'sort_by': 'popularity.desc'
    })

    # What are the best dramas?

    show = discover.discover_tv_shows({
        'with_genres': 18,
        'sort_by': 'vote_average.desc',
        'vote_count.gte': 10
    })

Login to your account and add some movie recommendations to your TMDb watchlist.

.. code:: python

    from tmdbv3api import Account
    from tmdbv3api import Authentication
    from tmdbv3api import TMDb, Movie

    USERNAME = "YOUR_USERNAME"
    PASSWORD = "YOUR_PASSWORD"

    tmdb = TMDb()
    tmdb.api_key = "YOUR_API_KEY"

    auth = Authentication(username=USERNAME, password=PASSWORD)

    account = Account()
    details = account.details()

    print("You are logged in as %s. Your account ID is %s." % (details.username, details.id))
    print("This session expires at: %s" % auth.expires_at)

    movie = Movie()

    s = movie.search("Gangs of New York")
    first_result = s[0]
    recommendations = movie.recommendations(first_result.id)

    for recommendation in recommendations:
        print("Adding %s (%s) to watchlist." % (recommendation.title, recommendation.release_date))
        account.add_to_watchlist(details.id, recommendation.id, "movie")


Pagination
~~~~~~~~~~

TMDb paginates most list and search endpoints: a response contains at most 20
items, and you can request at most 500 pages (10,000 items) per query. Methods
that paginate accept a ``page`` argument, and the response exposes ``page``,
``total_pages`` and ``total_results``, so you need to loop to get everything.

.. code:: python

    company = Company()

    movies = []
    page = 1
    while True:
        results = company.movies(882, page=page)
        movies.extend(results)
        if page >= int(results['total_pages']):
            break
        page += 1

Caching
~~~~~~~

Responses are cached in memory using an LRU cache that holds the most recent
128 requests. To change the size, set the ``TMDB_REQUEST_CACHE_MAXSIZE``
environment variable before importing the library (``0`` means unlimited, which
means memory use grows with the number of distinct requests).

.. code:: bash

    $ export TMDB_REQUEST_CACHE_MAXSIZE=512

You can also empty the cache at any time, or turn caching off completely:

.. code:: python

    tmdb.cache_clear()
    tmdb.cache = False

Running Tests
~~~~~~~~~~~~~

You can run the tests via the command line. You must export your TMDb API key and Session ID  as an environment variables.

Your Session ID can be obtained by running ``Authentication(username, password).session_id``

Mac
++++++++++++++++++++++++

.. code:: bash

    $ export TMDB_API_KEY='YOUR_API_KEY'
    $ export TMDB_SESSION_ID='YOUR_SESSION_ID'

Windows (Command Prompt)
++++++++++++++++++++++++

.. code:: bash

    $ setx TMDB_API_KEY "YOUR_API_KEY"
    $ setx TMDB_SESSION_ID "YOUR_SESSION_ID"

Windows (PowerShell)
++++++++++++++++++++++++

.. code:: bash

    $ $Env:TMDB_API_KEY="YOUR_API_KEY"
    $ $Env:TMDB_SESSION_ID="YOUR_SESSION_ID"

After you've set up your environmental variables then run:

.. code:: bash

    $ python -m unittest discover tests/
