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
search = movie.search('Mad Max')
for res in search:
print(res.id)
print(res.title)
print(res.overview)
print(res.poster_path)
print(res.vote_average)
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")
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/
Raw data
{
"_id": null,
"home_page": "https://github.com/AnthonyBloomer/tmdbv3api",
"name": "tmdbv3api",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "movie,tvmovie database,tmdb,wrapper,database,themoviedb,moviedb,api",
"author": "Anthony Bloomer",
"author_email": "ant0@protonmail.ch",
"download_url": "https://files.pythonhosted.org/packages/d7/1b/b1c4d45e7df81e92c92944f4835af2caa5d7fe55c61f717255da6e6c9c8e/tmdbv3api-1.9.0.tar.gz",
"platform": null,
"description": "tmdbv3api\n=========\n\n.. image:: https://travis-ci.org/AnthonyBloomer/tmdbv3api.svg?branch=master\n :target: https://travis-ci.org/AnthonyBloomer/tmdbv3api\n :alt: Build Status\n\n.. image:: https://codecov.io/gh/AnthonyBloomer/tmdbv3api/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/AnthonyBloomer/tmdbv3api\n :alt: codecov\n\n.. image:: https://img.shields.io/github/v/release/AnthonyBloomer/tmdbv3api\n :target: https://github.com/AnthonyBloomer/tmdbv3api/releases\n :alt: GitHub release (latest by date)\n\n.. image:: https://img.shields.io/pypi/v/tmdbv3api\n :target: https://pypi.org/project/tmdbv3api/\n :alt: PyPI\n\n.. image:: https://img.shields.io/pypi/dm/tmdbv3api.svg\n :target: https://pypi.org/project/tmdbv3api/\n :alt: Downloads\n\n.. image:: https://img.shields.io/github/commits-since/AnthonyBloomer/tmdbv3api/latest\n :target: https://github.com/AnthonyBloomer/tmdbv3api/commits/master\n :alt: GitHub commits since latest release (by date) for a branch\n\nA 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.\n\nRegister an account: https://www.themoviedb.org/account/signup\n\nCheck out the API documentation: https://developers.themoviedb.org/3/getting-started/introduction\n\nInstall\n~~~~~~~\n\ntmdbv3api is available on the Python Package Index (PyPI) at\nhttps://pypi.python.org/pypi/tmdbv3api\n\nYou can install tmdbv3api using pip.\n\n::\n\n $ pip install tmdbv3api\n\nUsage\n~~~~~\n\nThe first step is to initialize a TMDb object and set your API Key.\n\n.. code:: python\n\n from tmdbv3api import TMDb\n tmdb = TMDb()\n tmdb.api_key = 'YOUR_API_KEY'\n\nAlternatively, you can export your API key as an environment variable.\n\n.. code:: bash\n\n $ export TMDB_API_KEY='YOUR_API_KEY'\n\nOther configuration settings include defining your ``language`` and enabling ``debug`` mode, for example:\n\n.. code:: python\n\n tmdb.language = 'en'\n tmdb.debug = True\n\nThen to communicate with TMDb, create an instance of one of the objects\nand call that instances methods. For example, to retrieve movie\nrecommendations for a given movie id:\n\n.. code:: python\n\n from tmdbv3api import Movie\n\n movie = Movie()\n\n recommendations = movie.recommendations(movie_id=111)\n\n for recommendation in recommendations:\n print(recommendation.title)\n print(recommendation.overview)\n\nExamples\n~~~~~~~~\n\nGet the list of popular movies on The Movie Database. This list\nrefreshes every day.\n\n.. code:: python\n\n\n movie = Movie()\n popular = movie.popular()\n\n for p in popular:\n print(p.id)\n print(p.title)\n print(p.overview)\n print(p.poster_path)\n\n\nGet the primary information about a movie.\n\n.. code:: python\n\n m = movie.details(343611)\n\n print(m.title)\n print(m.overview)\n print(m.popularity)\n\nSearch for movies by title.\n\n.. code:: python\n\n search = movie.search('Mad Max')\n\n for res in search:\n print(res.id)\n print(res.title)\n print(res.overview)\n print(res.poster_path)\n print(res.vote_average)\n\nGet the similar movies for a specific movie id.\n\n.. code:: python\n\n similar = movie.similar(777)\n\n for result in similar:\n print(result.title)\n print(result.overview)\n\nSearch for TV shows by title.\n\n.. code:: python\n\n tv = TV()\n show = tv.search('Breaking Bad')\n\n for result in show:\n print(result.name)\n print(result.overview)\n\nGet the similar TV shows for a specific tv id.\n\n.. code:: python\n\n similar = tv.similar(1396)\n\n for show in similar:\n print(show.name)\n print(show.overview)\n\nGet the details of TV season for a specific tv id.\n\n.. code:: python\n\n season = Season()\n show_season = season.details(1396, 1)\n print(show_season.air_date)\n print(len(show_season.episodes))\n\nGet the general person information for a specific id.\n\n.. code:: python\n\n person = Person()\n p = person.details(12)\n\n print(p.name)\n print(p.biography)\n\nDiscover movies by different types of data like average rating, number\nof votes, genres and certifications.\n\n.. code:: python\n\n\n # What movies are in theatres?\n\n discover = Discover()\n movie = discover.discover_movies({\n 'primary_release_date.gte': '2017-01-20',\n 'primary_release_date.lte': '2017-01-25'\n })\n\n # What are the most popular movies?\n\n movie = discover.discover_movies({\n 'sort_by': 'popularity.desc'\n })\n\n # What are the most popular kids movies?\n\n movie = discover.discover_movies({\n 'certification_country': 'US',\n 'certification.lte': 'G',\n 'sort_by': 'popularity.desc'\n })\n\nDiscover TV shows by different types of data like average rating, number\nof votes, genres, the network they aired on and air dates.\n\n.. code:: python\n\n # What are the most popular TV shows?\n\n show = discover.discover_tv_shows({\n 'sort_by': 'popularity.desc'\n })\n\n # What are the best dramas?\n\n show = discover.discover_tv_shows({\n 'with_genres': 18,\n 'sort_by': 'vote_average.desc',\n 'vote_count.gte': 10\n })\n\nLogin to your account and add some movie recommendations to your TMDb watchlist.\n\n.. code:: python\n\n from tmdbv3api import Account\n from tmdbv3api import Authentication\n from tmdbv3api import TMDb, Movie\n\n USERNAME = \"YOUR_USERNAME\"\n PASSWORD = \"YOUR_PASSWORD\"\n\n tmdb = TMDb()\n tmdb.api_key = \"YOUR_API_KEY\"\n\n auth = Authentication(username=USERNAME, password=PASSWORD)\n\n account = Account()\n details = account.details()\n\n print(\"You are logged in as %s. Your account ID is %s.\" % (details.username, details.id))\n print(\"This session expires at: %s\" % auth.expires_at)\n\n movie = Movie()\n\n s = movie.search(\"Gangs of New York\")\n first_result = s[0]\n recommendations = movie.recommendations(first_result.id)\n\n for recommendation in recommendations:\n print(\"Adding %s (%s) to watchlist.\" % (recommendation.title, recommendation.release_date))\n account.add_to_watchlist(details.id, recommendation.id, \"movie\")\n\n\nRunning Tests\n~~~~~~~~~~~~~\n\nYou can run the tests via the command line. You must export your TMDb API key and Session ID as an environment variables.\n\nYour Session ID can be obtained by running ``Authentication(username, password).session_id``\n\nMac\n++++++++++++++++++++++++\n\n.. code:: bash\n\n $ export TMDB_API_KEY='YOUR_API_KEY'\n $ export TMDB_SESSION_ID='YOUR_SESSION_ID'\n\nWindows (Command Prompt)\n++++++++++++++++++++++++\n\n.. code:: bash\n\n $ setx TMDB_API_KEY \"YOUR_API_KEY\"\n $ setx TMDB_SESSION_ID \"YOUR_SESSION_ID\"\n\nWindows (PowerShell)\n++++++++++++++++++++++++\n\n.. code:: bash\n\n $ $Env:TMDB_API_KEY=\"YOUR_API_KEY\"\n $ $Env:TMDB_SESSION_ID=\"YOUR_SESSION_ID\"\n\nAfter you've set up your environmental variables then run:\n\n.. code:: bash\n\n $ python -m unittest discover tests/\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight Python library for The Movie Database (TMDb) API.",
"version": "1.9.0",
"project_urls": {
"Homepage": "https://github.com/AnthonyBloomer/tmdbv3api"
},
"split_keywords": [
"movie",
"tvmovie database",
"tmdb",
"wrapper",
"database",
"themoviedb",
"moviedb",
"api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "35fb9d575292bb7794a7a85bcdbf6c09928aae5ca2ae9f684f7fbbd902e281c4",
"md5": "adea0a0dd5bcb909c7fc6c5addc819f4",
"sha256": "2bcd8c6e8902397860715a71045f200ecc3ee06804ecf786cb4c1e09b2deeba8"
},
"downloads": -1,
"filename": "tmdbv3api-1.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "adea0a0dd5bcb909c7fc6c5addc819f4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 25500,
"upload_time": "2023-08-14T11:43:23",
"upload_time_iso_8601": "2023-08-14T11:43:23.482150Z",
"url": "https://files.pythonhosted.org/packages/35/fb/9d575292bb7794a7a85bcdbf6c09928aae5ca2ae9f684f7fbbd902e281c4/tmdbv3api-1.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d71bb1c4d45e7df81e92c92944f4835af2caa5d7fe55c61f717255da6e6c9c8e",
"md5": "8668bf95b9a40488b2c1a3771e543f50",
"sha256": "504c5da6b99c4516ff160a01576112d097f209c0534f943c15c4b56cbd92c33b"
},
"downloads": -1,
"filename": "tmdbv3api-1.9.0.tar.gz",
"has_sig": false,
"md5_digest": "8668bf95b9a40488b2c1a3771e543f50",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 26563,
"upload_time": "2023-08-14T11:43:24",
"upload_time_iso_8601": "2023-08-14T11:43:24.748366Z",
"url": "https://files.pythonhosted.org/packages/d7/1b/b1c4d45e7df81e92c92944f4835af2caa5d7fe55c61f717255da6e6c9c8e/tmdbv3api-1.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-14 11:43:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AnthonyBloomer",
"github_project": "tmdbv3api",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "tmdbv3api"
}
JSON
