Metadata-Version: 2.4
Name: auteur
Version: 1.0.2
Summary: Client library for fetching and parsing IMDb title data (with AWS WAF challenge handling).
Author: spiritualized
Project-URL: Repository, https://github.com/spiritualized/auteur
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: lxml>=5.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"

# 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

```bash
pip install auteur
```

## Examples

### Title page (`imdb_title`)

```python
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`)

```python
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).

```python
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/`](https://www.imdb.com/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`).

```python
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"])
```
