auteur 1.0.0

Client library for fetching and parsing IMDb title data (with AWS WAF challenge handling).

auteur

Python client for fetching and parsing IMDb title and person pages. It uses requests for HTTP, includes an AWS WAF challenge solver so that automated requests to www.imdb.com can succeed, and exposes an Auteur facade for titles and people (metadata such as title, year, type, runtime, genres), title find search, and advanced /search/title/ queries.

Install

pip install auteur

Examples

Title page (imdb_title)

from auteur import Auteur, AuteurConfig

config = AuteurConfig(language="en-US,en")
auteur = Auteur(config)
movie = auteur.imdb_title("0133093")
print(movie.title(), movie.year(), movie.genres())

Person page (imdb_person)

from auteur import Auteur, AuteurConfig

auteur = Auteur(AuteurConfig(language="en-US,en"))
person = auteur.imdb_person("0000206")  # digits only or nm… prefix both work
print(person.name())

Title find (title_search)

Uses IMDb find (/find/?s=tt&q=…). Results are ImdbTitle instances seeded from the hit list (full detail loads on demand when you call other methods).

from auteur import Auteur, AuteurConfig
from auteur.imdb_title_search import TitleSearch

auteur = Auteur(AuteurConfig(language="en-US,en"))

for title in auteur.title_search("the matrix"):
    print(title.title(), title.year())

movies_only = auteur.title_search("Cowboy Bebop", [TitleSearch.MOVIE])
first_five = auteur.title_search("Star Trek", max_results=5)

Advanced title search (title_search_advanced)

Structured filters on IMDb /search/title/. Each row is a dict (fields such as imdbid, title, year, type, rank, episode metadata when applicable). Locale can affect how result rows parse; if parsing looks wrong, try another AuteurConfig(language=…) (for example en-GB).

from auteur import Auteur, AuteurConfig
from auteur.imdb_title_search_advanced import TitleSearchAdvanced

auteur = Auteur(AuteurConfig(language="en-US,en"))
search = auteur.title_search_advanced()
search.set_title("Firefly")
search.set_title_types([TitleSearchAdvanced.TV_EPISODE])
search.set_year(2003)
search.set_sort(TitleSearchAdvanced.SORT_NUM_VOTES)

for row in search.search():
    print(row["imdbid"], row["title"], row["year"], row["type"])

Build and publish

python -m build --sdist
python -m twine check dist/*
python -m twine upload dist/*