Contributing
Issues¶
If you notice an issue with phylm or would like to suggest a feature or just have a general question, please raise an issue on GitHub. If it's an issue that needs debugging please make sure to include the version of phylm in the issue description. You can retrieve the version with the following:
pip freeze | grep phylm
+Pull Requests¶
If you would like to contribute to the repo, you would be most welcome. If you're tackling an existing issue please comment on the issue that you'd like to take it on. If it's a new feature/bug, please first raise an issue. If it's a trivial change (typos, documentation etc.) then no need to raise an issue.
Local Development¶
In order to work on your contribution, you'll need to first fork the repo and then clone it to your local machine:
git clone git@github.com:<your username>/phylm.git
+cd phylm
+You'll need python 3.8 or 3.9 to run this package. You can follow the instructions here to install and use these versions.
This package uses poetry to manage dependencies. Ensure you have poetry installed, instructions here and run:
poetry install
+This will install the dependencies into a .venv virtual environment. You can activate the env with either source .venv/bin/activate or poetry shell.
Next install the pre-commit hooks with:
pre-commit install
+Nox is used to run tests, linters, type checkers etc. These are all run in the CI and on git commit but if you'd like to run them manually, you can do so with, eg:
nox --session=tests
+This will run the tests for all versions of python.
See here for more information on running nox locally.
If you're making changes that will require updates to the documentation, please do so accordingly. Documentation lives in the docs/ directory and can be served locally with:
mkdocs serve
+See here for more information on working with mkdocs.
Once you're ready with your shiny, TDD'd feature, commit, push, and open a pull request and I'll be happy to review. If you're having issues with any of this setup please do let me know and I'll try and help.
Last update: 2023-10-18
IMDb
Usage¶
To access IMDb data points, first ensure you have loaded the IMDb source through:
await phylm.load_source("imdb")
+Alternatively you can instantiate the IMDb source class directly through:
from phylm.sources import Imdb
+
+imdb = Imdb(raw_title="The Matrix", raw_year=1999) # raw_year is optional
+await imdb.load_source()
+Movie ID¶
If you know the IMDb movie ID you can instantiate the Phylm class with an imdb_id property:
from phylm.sources import Imdb
+
+imdb = Imdb(raw_title="The Matrix", imdb_id="0133093")
+Then, when running load_source for imdb, phylm will first perform a search based on the ID. If the ID is valid the result will be selected, if not then it will fall back to a title search.
Alternatively, you can pass it to load_source with "imdb" as the first argument:
await phylm.load_source("imdb", imdb_id="0133093")
+Or instantiate the IMDb source class with the ID:
from phylm.sources import Imdb
+
+imdb = Imdb(movie_id="0133093")
+If instantiating the class directly you must supply at least one of movie_id or raw_title, otherwise a ValueError will be raised.
Reference¶
Class to abstract an IMDb movie object.
id: Optional[str] property ¶
Return the IMDb id.
Returns:
| Type | Description |
|---|---|
Optional[str] | the id of the movie |
plot: Optional[str] property ¶
Return the plot.
Returns:
| Type | Description |
|---|---|
Optional[str] | the plot of the movie |
rating: Optional[float] property ¶
Return the IMDb rating.
Returns:
| Type | Description |
|---|---|
Optional[float] | the rating of the movie |
runtime: Optional[str] property ¶
Return the runtime.
Returns:
| Type | Description |
|---|---|
Optional[str] | the runtime of the movie |
title: Optional[str] property ¶
Return the IMDb title.
Returns:
| Type | Description |
|---|---|
Optional[str] | the title of the movie |
year: Optional[int] property ¶
Return the movie's year.
Returns:
| Type | Description |
|---|---|
Optional[int] | the year the movie was made |
__init__(raw_title: Optional[str] = None, movie_id: Optional[str] = None, raw_year: Optional[int] = None) -> None ¶
Initialize the object.
Note that at least one of raw_title or movie_id must be given to be used as a search term. movie_id is preferred over raw_title.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
raw_title | Optional[str] | the title of the movie | None |
movie_id | Optional[str] | the | None |
raw_year | Optional[int] | an optional year for improved matching if only title is given | None |
Raises:
| Type | Description |
|---|---|
ValueError | if neither |
cast(limit: int = 5) -> List[str] ¶
Return the cast.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
limit | int | an optional number of cast members to return | 5 |
Returns:
| Type | Description |
|---|---|
List[str] | a list of the movie's cast members |
directors(limit: int = 3) -> List[str] ¶
Return the director(s).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
limit | int | an optional number of director to return | 3 |
Returns:
| Type | Description |
|---|---|
List[str] | a list of the movie's directors |
genres(limit: int = 3) -> List[str] ¶
Return the genres.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
limit | int | an optional number of genres to return | 3 |
Returns:
| Type | Description |
|---|---|
List[str] | a list of the movie's genres |
load_source() -> None async ¶
Asynchronously load the data for from the source.
Last update: 2023-10-18
Phylm
When deciding which film to watch next, it can be helpful to have some key datapoints at your fingertips, for example, the genre, the cast, the Metacritic score and, perhaps most importantly, the runtime. This package provides a Phylm class to gather information from various sources for a given film.
Installing¶
pip install phylm
+Example¶
>>> import asyncio
+>>> from phylm import Phylm
+>>> p = Phylm("The Matrix")
+>>> asyncio.run(p.load_source("imdb"))
+>>> p.imdb.rating
+8.7
+This package uses web scraping for the Rotten Tomatoes and Metacritic results and is therefore at the mercy of changes made to those webpages.
Last update: 2023-10-18
Metacritic
Usage¶
To access Metacritic data points, first ensure you have loaded the Metacritic source through:
await phylm.load_source("mtc")
+Alternatively you can instantiate the Metacritic source class directly through:
from phylm.sources import Mtc
+
+mtc = Mtc(raw_title="The Matrix", raw_year=1999) # raw_year is optional
+await mtc.load_source()
+Reference¶
Class to abstract a Metacritic movie search result.
rating: Optional[str] property ¶
Return the rating.
Returns:
| Type | Description |
|---|---|
Optional[str] | the mtc rating |
title: Optional[str] property ¶
Return the title.
Returns:
| Type | Description |
|---|---|
Optional[str] | the title of the movie |
year: Optional[int] property ¶
Return the year.
Returns:
| Type | Description |
|---|---|
Optional[int] | the year of the movie |
__init__(raw_title: str, raw_year: Optional[int] = None) -> None ¶
Initialize the object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
raw_title | str | the given title of the movie | required |
raw_year | Optional[int] | an optional year for improved matching | None |
load_source(session: Optional[ClientSession] = None) -> None async ¶
Asynchronously load the data from the source.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session | Optional[ClientSession] | an optional instance of | None |
Last update: 2023-10-18
Phylm
This is the main entrypoint class.
Usage¶
First instantiate the class with a title property:
from phylm import Phylm
+
+p = Phylm(title="The Matrix")
+You can also provide a year property for improved matching:
from phylm import Phylm
+
+p = Phylm(title="The Matrix", year=1999)
+Next, asynchronously load a source through either load_sources or load_source:
await p.load_sources(["imdb", "rt"])
+await p.load_source("mtc")
+The available sources are:
"imdb" # IMDb
+"rt" # Rotten Tomatoes
+"mtc" # Metacritic
+"tmdb" # TMDB
+Now the source will be available through a property of the same name and datapoints on that source can be accessed:
>>> p.imdb
+<phylm.sources.imdb.Imdb object at 0x108a94810>
+>>> p.imdb.rating
+8.8
+Low Confidence¶
phylm will try to match the given title with the results through an exact match on the title. If phylm can't find an exact match then it will select the first result and set a low_confidence flag to True. This and the year method on a source can be helpful for validating that the result is the desired one:
from phylm import Phylm
+p = Phylm("Ambiguous Movie") # suppose this movie was released in 1999
+await p.load_source("imdb")
+if p.imdb.low_confidence and p.imdb.year != 1999:
+ # it's unlikely we're dealing with the right "Ambigous Movie"
+See the docs for a source for a full list of the available data points.
Reference¶
Main Phylm entrypoint.
imdb: Imdb property ¶
Return the IMDb data.
Returns:
| Type | Description |
|---|---|
Imdb | The IMDb data |
Raises:
| Type | Description |
|---|---|
SourceNotLoadedError | if the source is not loaded |
mtc: Mtc property ¶
Return the Metacritic data.
Returns:
| Type | Description |
|---|---|
Mtc | The Metacritic data |
Raises:
| Type | Description |
|---|---|
SourceNotLoadedError | if the source is not loaded |
rt: Rt property ¶
Return the Rotten Tomatoes data.
Returns:
| Type | Description |
|---|---|
Rt | The Rotten Tomatoes data |
Raises:
| Type | Description |
|---|---|
SourceNotLoadedError | if the source is not loaded |
tmdb: Tmdb property ¶
Return the TMDB data.
Returns:
| Type | Description |
|---|---|
Tmdb | The TMDB data |
Raises:
| Type | Description |
|---|---|
SourceNotLoadedError | if the source is not loaded |
__init__(title: str, imdb_id: Optional[str] = None, year: Optional[int] = None, tmdb_id: Optional[str] = None) -> None ¶
Initialize a Phylm object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
title | str | the title of the movie | required |
imdb_id | Optional[str] | an optional | None |
year | Optional[int] | an optional year of the movie | None |
tmdb_id | Optional[str] | an optional | None |
load_source(source: str, imdb_id: Optional[str] = None, session: Optional[ClientSession] = None, tmdb_id: Optional[str] = None) -> Phylm async ¶
Asynchronously load the film data for a source.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source | str | the desired source | required |
imdb_id | Optional[str] | an optional | None |
session | Optional[ClientSession] | an optional instance of | None |
tmdb_id | Optional[str] | an optional | None |
Returns:
| Type | Description |
|---|---|
Phylm | the instance |
Raises:
| Type | Description |
|---|---|
UnrecognizedSourceError | if the source is not recognized |
load_sources(sources: List[str]) -> Phylm async ¶
Asynchronously load multiple sources.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sources | List[str] | a list of the desired sources | required |
Returns:
| Type | Description |
|---|---|
Phylm | the instance |
Last update: 2023-10-18
Rotten Tomatoes
Usage¶
To access Rotten Tomatoes data points, first ensure you have loaded the Rotten Tomatoes source through:
await phylm.load_source("rt")
+Alternatively you can instantiate the Rotten Tomatoes source class directly through:
from phylm.sources import Rt
+
+rot_tom = Rt(raw_title="The Matrix", raw_year=1999) # raw_year is optional
+await rot_tom.load_source()
+Reference¶
Class to abstract a Rotten Tomatoes result.
title: Optional[str] property ¶
Return the title.
Returns:
| Type | Description |
|---|---|
Optional[str] | the title of the movie |
tomato_score: Optional[str] property ¶
Return the Tomatometer Score.
Returns:
| Type | Description |
|---|---|
Optional[str] | the tomatometer score |
year: Optional[str] property ¶
Return the year.
Returns:
| Type | Description |
|---|---|
Optional[str] | the year of the movie |
__init__(raw_title: str, raw_year: Optional[int] = None) -> None ¶
Initialize the object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
raw_title | str | the given title of the movie | required |
raw_year | Optional[int] | an optional year for improved matching | None |
load_source(session: Optional[ClientSession] = None) -> None async ¶
Asynchronously load the data from the source.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session | Optional[ClientSession] | an optional instance of | None |
Last update: 2023-10-18
When deciding which film to watch next, it can be helpful to have some key datapoints at your fingertips, for example, the genre, the cast, the Metacritic score and, perhaps most importantly, the runtime. This package provides a Phylm class to gather information from various sources for a given film.
"},{"location":"#installing","title":"Installing","text":"pip install phylm\n>>> import asyncio\n>>> from phylm import Phylm\n>>> p = Phylm(\"The Matrix\")\n>>> asyncio.run(p.load_source(\"imdb\"))\n>>> p.imdb.rating\n8.7\nThis package uses web scraping for the Rotten Tomatoes and Metacritic results and is therefore at the mercy of changes made to those webpages.
"},{"location":"contributing/","title":"Contributing","text":""},{"location":"contributing/#issues","title":"Issues","text":"If you notice an issue with phylm or would like to suggest a feature or just have a general question, please raise an issue on GitHub. If it's an issue that needs debugging please make sure to include the version of phylm in the issue description. You can retrieve the version with the following:
pip freeze | grep phylm\nIf you would like to contribute to the repo, you would be most welcome. If you're tackling an existing issue please comment on the issue that you'd like to take it on. If it's a new feature/bug, please first raise an issue. If it's a trivial change (typos, documentation etc.) then no need to raise an issue.
"},{"location":"contributing/#local-development","title":"Local Development","text":"In order to work on your contribution, you'll need to first fork the repo and then clone it to your local machine:
git clone git@github.com:<your username>/phylm.git\ncd phylm\nYou'll need python 3.8 or 3.9 to run this package. You can follow the instructions here to install and use these versions.
This package uses poetry to manage dependencies. Ensure you have poetry installed, instructions here and run:
poetry install\nThis will install the dependencies into a .venv virtual environment. You can activate the env with either source .venv/bin/activate or poetry shell.
Next install the pre-commit hooks with:
pre-commit install\nNox is used to run tests, linters, type checkers etc. These are all run in the CI and on git commit but if you'd like to run them manually, you can do so with, eg:
nox --session=tests\nThis will run the tests for all versions of python.
See here for more information on running nox locally.
If you're making changes that will require updates to the documentation, please do so accordingly. Documentation lives in the docs/ directory and can be served locally with:
mkdocs serve\nSee here for more information on working with mkdocs.
Once you're ready with your shiny, TDD'd feature, commit, push, and open a pull request and I'll be happy to review. If you're having issues with any of this setup please do let me know and I'll try and help.
"},{"location":"imdb/","title":"IMDb","text":""},{"location":"imdb/#usage","title":"Usage","text":"To access IMDb data points, first ensure you have loaded the IMDb source through:
await phylm.load_source(\"imdb\")\nAlternatively you can instantiate the IMDb source class directly through:
from phylm.sources import Imdb\n\nimdb = Imdb(raw_title=\"The Matrix\", raw_year=1999) \u00a0# raw_year is optional\nawait imdb.load_source()\nIf you know the IMDb movie ID you can instantiate the Phylm class with an imdb_id property:
from phylm.sources import Imdb\n\nimdb = Imdb(raw_title=\"The Matrix\", imdb_id=\"0133093\")\nThen, when running load_source for imdb, phylm will first perform a search based on the ID. If the ID is valid the result will be selected, if not then it will fall back to a title search.
Alternatively, you can pass it to load_source with \"imdb\" as the first argument:
await phylm.load_source(\"imdb\", imdb_id=\"0133093\")\nOr instantiate the IMDb source class with the ID:
from phylm.sources import Imdb\n\nimdb = Imdb(movie_id=\"0133093\")\nIf instantiating the class directly you must supply at least one of movie_id or raw_title, otherwise a ValueError will be raised.
Class to abstract an IMDb movie object.
"},{"location":"imdb/#phylm.sources.imdb.Imdb.id","title":"id: Optional[str] property","text":"Return the IMDb id.
Returns:
Type DescriptionOptional[str] the id of the movie
"},{"location":"imdb/#phylm.sources.imdb.Imdb.plot","title":"plot: Optional[str] property","text":"Return the plot.
Returns:
Type DescriptionOptional[str] the plot of the movie
"},{"location":"imdb/#phylm.sources.imdb.Imdb.rating","title":"rating: Optional[float] property","text":"Return the IMDb rating.
Returns:
Type DescriptionOptional[float] the rating of the movie
"},{"location":"imdb/#phylm.sources.imdb.Imdb.runtime","title":"runtime: Optional[str] property","text":"Return the runtime.
Returns:
Type DescriptionOptional[str] the runtime of the movie
"},{"location":"imdb/#phylm.sources.imdb.Imdb.title","title":"title: Optional[str] property","text":"Return the IMDb title.
Returns:
Type DescriptionOptional[str] the title of the movie
"},{"location":"imdb/#phylm.sources.imdb.Imdb.year","title":"year: Optional[int] property","text":"Return the movie's year.
Returns:
Type DescriptionOptional[int] the year the movie was made
"},{"location":"imdb/#phylm.sources.imdb.Imdb.__init__","title":"__init__(raw_title: Optional[str] = None, movie_id: Optional[str] = None, raw_year: Optional[int] = None) -> None","text":"Initialize the object.
Note that at least one of raw_title or movie_id must be given to be used as a search term. movie_id is preferred over raw_title.
Parameters:
Name Type Description Defaultraw_title Optional[str] the title of the movie
None movie_id Optional[str] the IMDb id of the movie
None raw_year Optional[int] an optional year for improved matching if only title is given
None Raises:
Type DescriptionValueError if neither raw_title nor movie_id is supplied
cast(limit: int = 5) -> List[str]","text":"Return the cast.
Parameters:
Name Type Description Defaultlimit int an optional number of cast members to return
5 Returns:
Type DescriptionList[str] a list of the movie's cast members
"},{"location":"imdb/#phylm.sources.imdb.Imdb.directors","title":"directors(limit: int = 3) -> List[str]","text":"Return the director(s).
Parameters:
Name Type Description Defaultlimit int an optional number of director to return
3 Returns:
Type DescriptionList[str] a list of the movie's directors
"},{"location":"imdb/#phylm.sources.imdb.Imdb.genres","title":"genres(limit: int = 3) -> List[str]","text":"Return the genres.
Parameters:
Name Type Description Defaultlimit int an optional number of genres to return
3 Returns:
Type DescriptionList[str] a list of the movie's genres
"},{"location":"imdb/#phylm.sources.imdb.Imdb.load_source","title":"load_source() -> None async","text":"Asynchronously load the data for from the source.
"},{"location":"mtc/","title":"Metacritic","text":""},{"location":"mtc/#usage","title":"Usage","text":"To access Metacritic data points, first ensure you have loaded the Metacritic source through:
await phylm.load_source(\"mtc\")\nAlternatively you can instantiate the Metacritic source class directly through:
from phylm.sources import Mtc\n\nmtc = Mtc(raw_title=\"The Matrix\", raw_year=1999) \u00a0# raw_year is optional\nawait mtc.load_source()\nClass to abstract a Metacritic movie search result.
"},{"location":"mtc/#phylm.sources.mtc.Mtc.rating","title":"rating: Optional[str] property","text":"Return the rating.
Returns:
Type DescriptionOptional[str] the mtc rating
"},{"location":"mtc/#phylm.sources.mtc.Mtc.title","title":"title: Optional[str] property","text":"Return the title.
Returns:
Type DescriptionOptional[str] the title of the movie
"},{"location":"mtc/#phylm.sources.mtc.Mtc.year","title":"year: Optional[int] property","text":"Return the year.
Returns:
Type DescriptionOptional[int] the year of the movie
"},{"location":"mtc/#phylm.sources.mtc.Mtc.__init__","title":"__init__(raw_title: str, raw_year: Optional[int] = None) -> None","text":"Initialize the object.
Parameters:
Name Type Description Defaultraw_title str the given title of the movie
requiredraw_year Optional[int] an optional year for improved matching
None"},{"location":"mtc/#phylm.sources.mtc.Mtc.load_source","title":"load_source(session: Optional[ClientSession] = None) -> None async","text":"Asynchronously load the data from the source.
Parameters:
Name Type Description Defaultsession Optional[ClientSession] an optional instance of aiohttp.ClientSession in which to run the request
None"},{"location":"phylm/","title":"Phylm","text":"This is the main entrypoint class.
"},{"location":"phylm/#usage","title":"Usage","text":"First instantiate the class with a title property:
from phylm import Phylm\n\np = Phylm(title=\"The Matrix\")\nYou can also provide a year property for improved matching:
from phylm import Phylm\n\np = Phylm(title=\"The Matrix\", year=1999)\nNext, asynchronously load a source through either load_sources or load_source:
await p.load_sources([\"imdb\", \"rt\"])\nawait p.load_source(\"mtc\")\nThe available sources are:
\"imdb\" # IMDb\n\"rt\" # Rotten Tomatoes\n\"mtc\" # Metacritic\n\"tmdb\" # TMDB\nNow the source will be available through a property of the same name and datapoints on that source can be accessed:
>>> p.imdb\n<phylm.sources.imdb.Imdb object at 0x108a94810>\n>>> p.imdb.rating\n8.8\nphylm will try to match the given title with the results through an exact match on the title. If phylm can't find an exact match then it will select the first result and set a low_confidence flag to True. This and the year method on a source can be helpful for validating that the result is the desired one:
from phylm import Phylm\np = Phylm(\"Ambiguous Movie\") # suppose this movie was released in 1999\nawait p.load_source(\"imdb\")\nif p.imdb.low_confidence and p.imdb.year != 1999:\n # it's unlikely we're dealing with the right \"Ambigous Movie\"\nSee the docs for a source for a full list of the available data points.
"},{"location":"phylm/#reference","title":"Reference","text":"Main Phylm entrypoint.
imdb: Imdb property","text":"Return the IMDb data.
Returns:
Type DescriptionImdb The IMDb data
Raises:
Type DescriptionSourceNotLoadedError if the source is not loaded
"},{"location":"phylm/#phylm.phylm.Phylm.mtc","title":"mtc: Mtc property","text":"Return the Metacritic data.
Returns:
Type DescriptionMtc The Metacritic data
Raises:
Type DescriptionSourceNotLoadedError if the source is not loaded
"},{"location":"phylm/#phylm.phylm.Phylm.rt","title":"rt: Rt property","text":"Return the Rotten Tomatoes data.
Returns:
Type DescriptionRt The Rotten Tomatoes data
Raises:
Type DescriptionSourceNotLoadedError if the source is not loaded
"},{"location":"phylm/#phylm.phylm.Phylm.tmdb","title":"tmdb: Tmdb property","text":"Return the TMDB data.
Returns:
Type DescriptionTmdb The TMDB data
Raises:
Type DescriptionSourceNotLoadedError if the source is not loaded
"},{"location":"phylm/#phylm.phylm.Phylm.__init__","title":"__init__(title: str, imdb_id: Optional[str] = None, year: Optional[int] = None, tmdb_id: Optional[str] = None) -> None","text":"Initialize a Phylm object.
Parameters:
Name Type Description Defaulttitle str the title of the movie
requiredimdb_id Optional[str] an optional IMDb ID of the movie
None year Optional[int] an optional year of the movie
None tmdb_id Optional[str] an optional TMDB ID of the movie
None"},{"location":"phylm/#phylm.phylm.Phylm.load_source","title":"load_source(source: str, imdb_id: Optional[str] = None, session: Optional[ClientSession] = None, tmdb_id: Optional[str] = None) -> Phylm async","text":"Asynchronously load the film data for a source.
Parameters:
Name Type Description Defaultsource str the desired source
requiredimdb_id Optional[str] an optional IMDb id which will be used to load the imdb data instead of a basic search on the title
None session Optional[ClientSession] an optional instance of aiohttp.ClientSession in which to run the request
None tmdb_id Optional[str] an optional TMDB id which will be used to load the TMDB data instead of a basic search on the title
None Returns:
Type DescriptionPhylm the instance
Raises:
Type DescriptionUnrecognizedSourceError if the source is not recognized
"},{"location":"phylm/#phylm.phylm.Phylm.load_sources","title":"load_sources(sources: List[str]) -> Phylm async","text":"Asynchronously load multiple sources.
Parameters:
Name Type Description Defaultsources List[str] a list of the desired sources
requiredReturns:
Type DescriptionPhylm the instance
"},{"location":"rt/","title":"Rotten Tomatoes","text":""},{"location":"rt/#usage","title":"Usage","text":"To access Rotten Tomatoes data points, first ensure you have loaded the Rotten Tomatoes source through:
await phylm.load_source(\"rt\")\nAlternatively you can instantiate the Rotten Tomatoes source class directly through:
from phylm.sources import Rt\n\nrot_tom = Rt(raw_title=\"The Matrix\", raw_year=1999) \u00a0# raw_year is optional\nawait rot_tom.load_source()\nClass to abstract a Rotten Tomatoes result.
"},{"location":"rt/#phylm.sources.rt.Rt.title","title":"title: Optional[str] property","text":"Return the title.
Returns:
Type DescriptionOptional[str] the title of the movie
"},{"location":"rt/#phylm.sources.rt.Rt.tomato_score","title":"tomato_score: Optional[str] property","text":"Return the Tomatometer Score.
Returns:
Type DescriptionOptional[str] the tomatometer score
"},{"location":"rt/#phylm.sources.rt.Rt.year","title":"year: Optional[str] property","text":"Return the year.
Returns:
Type DescriptionOptional[str] the year of the movie
"},{"location":"rt/#phylm.sources.rt.Rt.__init__","title":"__init__(raw_title: str, raw_year: Optional[int] = None) -> None","text":"Initialize the object.
Parameters:
Name Type Description Defaultraw_title str the given title of the movie
requiredraw_year Optional[int] an optional year for improved matching
None"},{"location":"rt/#phylm.sources.rt.Rt.load_source","title":"load_source(session: Optional[ClientSession] = None) -> None async","text":"Asynchronously load the data from the source.
Parameters:
Name Type Description Defaultsession Optional[ClientSession] an optional instance of aiohttp.ClientSession in which to run the request
None"},{"location":"tmdb/","title":"TMDB","text":""},{"location":"tmdb/#usage","title":"Usage","text":"To access TMDB data points, first ensure you have loaded the TMDB source through:
await phylm.load_source(\"tmdb\")\nAlternatively you can instantiate the TMDB source class directly through:
from phylm.sources import Tmdb\n\ntmdb = Tmdb(raw_title=\"The Matrix\", raw_year=1999) \u00a0# raw_year is optional\nawait tmdb.load_source()\nIf you know the TMDB movie ID you can instantiate the Phylm class with a tmdb_id property:
from phylm.sources import Tmdb\n\ntmdb = Tmdb(raw_title=\"The Matrix\", tmdb_id=\"609\")\nThen, when running load_source for tmdb, phylm will first perform a search based on the ID. If the ID is valid the result will be selected, if not then it will fall back to a title search.
Alternatively, you can pass it to load_source with \"tmdb\" as the first argument:
await phylm.load_source(\"tmdb\", tmdb_id=\"609\")\nOr instantiate the TMDB source class with the ID:
from phylm.sources import Tmdb\n\ntmdb = Tmdb(movie_id=\"0133093\")\nIf instantiating the class directly you must supply at least one of movie_id or raw_title, otherwise a ValueError will be raised.
Note that TMDB doesn't provide any fuzzy search for title, only exact matches are returned.
"},{"location":"tmdb/#reference","title":"Reference","text":"Class to abstract a TMDB result.
"},{"location":"tmdb/#phylm.sources.tmdb.Tmdb.id","title":"id: Optional[str] property","text":"Return the TMDB id.
Returns:
Type DescriptionOptional[str] the id of the movie
"},{"location":"tmdb/#phylm.sources.tmdb.Tmdb.imdb_id","title":"imdb_id: Optional[str] property","text":"Return the IMDb id.
Returns:
Type DescriptionOptional[str] the IMDb id of the movie
"},{"location":"tmdb/#phylm.sources.tmdb.Tmdb.plot","title":"plot: Optional[str] property","text":"Return the plot.
Returns:
Type DescriptionOptional[str] the plot of the movie
"},{"location":"tmdb/#phylm.sources.tmdb.Tmdb.rating","title":"rating: Optional[float] property","text":"Return the TMDB rating.
Returns:
Type DescriptionOptional[float] the rating of the movie
"},{"location":"tmdb/#phylm.sources.tmdb.Tmdb.release_date","title":"release_date: Optional[str] property","text":"Return the movie's release_date.
Returns:
Type DescriptionOptional[str] the release date of the movie
"},{"location":"tmdb/#phylm.sources.tmdb.Tmdb.runtime","title":"runtime: Optional[int] property","text":"Return the runtime.
Returns:
Type DescriptionOptional[int] the runtime of the movie
"},{"location":"tmdb/#phylm.sources.tmdb.Tmdb.title","title":"title: Optional[str] property","text":"Return the TMDB title.
Returns:
Type DescriptionOptional[str] the title of the movie
"},{"location":"tmdb/#phylm.sources.tmdb.Tmdb.year","title":"year: Optional[int] property","text":"Return the movie's year.
Returns:
Type DescriptionOptional[int] the year the movie was made
"},{"location":"tmdb/#phylm.sources.tmdb.Tmdb.__init__","title":"__init__(raw_title: Optional[str] = None, movie_id: Optional[str] = None, raw_year: Optional[int] = None, api_key: Optional[str] = None, session: Optional[ClientSession] = None) -> None","text":"Initialize the object.
Note that at least one of raw_title or movie_id must be given to be used as a search term. movie_id is preferred over raw_title.
Parameters:
Name Type Description Defaultraw_title Optional[str] the title of the movie. Note that TMDB doesn't support fuzzy search.
None movie_id Optional[str] the TMDB id of the movie.
None raw_year Optional[int] an optional year for improved matching if only title is given.
None api_key Optional[str] a TMDB api key. Must be supplied here or as an env var
None session Optional[ClientSession] a aiohttp.ClientSession instance. One will be created if not supplied.
None Raises:
Type DescriptionValueError if neither raw_title nor movie_id is supplied.
genres(limit: int = 3) -> List[str]","text":"Return the genres.
Parameters:
Name Type Description Defaultlimit int an optional number of genres to return
3 Returns:
Type DescriptionList[str] a list of the movie's genres
"},{"location":"tmdb/#phylm.sources.tmdb.Tmdb.load_source","title":"load_source(session: Optional[ClientSession] = None) -> None async","text":"Asynchronously load the data for from the source.
Parameters:
Name Type Description Defaultsession Optional[ClientSession] an optional aiohttp.ClientSession instance
None"},{"location":"tools/","title":"Tools","text":"phylm also offers some tools and utilities related to movies.
For a given movie title query you can return a list of search results from IMDb through search_movies:
>>> from phylm.tools import search_movies\n>>> search_movies(\"the matrix\")\n[{\n 'title': 'The Matrix',\n 'kind': 'movie',\n 'year': 1999,\n 'cover_photo': 'https://some-url.com',\n 'imdb_id': '0133093',\n}, {\n 'title': 'The Matrix Reloaded',\n 'kind': 'movie',\n 'year': 2003,\n 'cover_photo': 'https://some-url.com',\n 'imdb_id': '0234215',\n}, {\n...\nphylm.tools.search_movies(query: str) -> List[Dict[str, Union[str, int]]]","text":"Return a list of search results for a query.
Parameters:
Name Type Description Defaultquery str the search query
requiredReturns:
Type DescriptionList[Dict[str, Union[str, int]]] a list of search results
"},{"location":"tools/#tmdb","title":"TMDB","text":"phylm also provides tools to interact with The Movie Database (TMDb).
To use TMDb tools you'll need to sign up for an API key, instructions here. Once you have your key, export it as an env var called TMDB_API_KEY so that it's available to use in these tools. You also have the option of passing in the key as an argument to each function.
For a given movie title query you can return a list of search results from TMDb through search_tmdb_movies. Note that this search performs a lot quicker than the imdb search_movies.
>>> from phylm.tools import search_tmdb_movies\n>>> search_tmdb_movies(\"The Matrix\", api_key=\"abc\") #\u00a0the api key can be provided as an env var instead\n[{\n 'adult': False,\n 'backdrop_path': '/fNG7i7RqMErkcqhohV2a6cV1Ehy.jpg',\n 'genre_ids': [28, 878],\n 'id': 603,\n 'original_language': 'en',\n 'original_title': 'The Matrix',\n 'overview': 'Set in the 22nd century, The Matrix tells the story of a computer hacker...'\n 'popularity': 79.956,\n 'poster_path': '/f89U3ADr1oiB1s9GkdPOEpXUk5H.jpg',\n 'release_date': '1999-03-30',\n 'title': 'The Matrix',\n 'video': False,\n 'vote_average': 8.2,\n 'vote_count': 20216,\n}, {\n ...\n}\nBy default the release_date will be the US release date. You can specify a different region by providing a region argument:
>>> from phylm.tools import search_tmdb_movies\n>>> search_tmdb_movies(\"The Matrix\", region=\"gb\")\n[{\n 'id': 603,\n ...\n 'release_date': '1999-06-11',\n 'title': 'The Matrix',\n ...\n}, {\n ...\n}\nphylm.tools.search_tmdb_movies(query: str, api_key: Optional[str] = None, region: Optional[str] = None) -> List[Dict[str, Any]]","text":"Search for movies on TMDb.
Parameters:
Name Type Description Defaultquery str the query string
requiredapi_key Optional[str] an api_key can either be provided here or through a TMDB_API_KEY env var
None region Optional[str] an optional region to provide with the search request, affects the release_date value returned, must be provided in ISO 3166-1 format (eg. \"us\" or \"gb\")
None Returns:
Type DescriptionList[Dict[str, Any]] List[Dict[str, Any]]: the search results
"},{"location":"tools/#get-streaming-providers","title":"Get streaming providers","text":"For a given movie TMDb id and list of regions, you can return a list of streaming providers from TMDb via Just Watch through get_streaming_providers.
>>> from phylm.tools import get_streaming_providers\n>>> get_streaming_providers(tmdb_movie_id=\"438631\", regions=[\"gb\"], api_key=\"abc\")\n{\n 'gb': {\n 'link': 'https://www.themoviedb.org/movie/438631-dune/watch?locale=GB',\n 'rent': [{\n 'display_priority': 8,\n 'logo_path': '/pZgeSWpfvD59x6sY6stT5c6uc2h.jpg',\n 'provider_id': 130,\n 'provider_name': 'Sky Store',\n }],\n },\n}\nConsult the TMDb docs for more information on the data that's returned.
"},{"location":"tools/#phylm.tools.get_streaming_providers","title":"phylm.tools.get_streaming_providers(tmdb_movie_id: str, regions: List[str], api_key: Optional[str] = None) -> Dict[str, Any]","text":"Return a list of streaming providers for a given movie.
Parameters:
Name Type Description Defaulttmdb_movie_id str the tmdb id of the movie
requiredregions List[str] a list of regions to trim down the return list
requiredapi_key Optional[str] an api_key can either be provided here or through a TMDB_API_KEY env var
None Returns:
Type DescriptionDict[str, Any] Dict[str, Any]: a dictionary of streaming providers, keyed by region name
"}]} \ No newline at end of file diff --git a/sitemap.xml b/sitemap.xml new file mode 100644 index 0000000..7c3dd51 --- /dev/null +++ b/sitemap.xml @@ -0,0 +1,43 @@ + +TMDB
Usage¶
To access TMDB data points, first ensure you have loaded the TMDB source through:
await phylm.load_source("tmdb")
+Alternatively you can instantiate the TMDB source class directly through:
from phylm.sources import Tmdb
+
+tmdb = Tmdb(raw_title="The Matrix", raw_year=1999) # raw_year is optional
+await tmdb.load_source()
+Movie ID¶
If you know the TMDB movie ID you can instantiate the Phylm class with a tmdb_id property:
from phylm.sources import Tmdb
+
+tmdb = Tmdb(raw_title="The Matrix", tmdb_id="609")
+Then, when running load_source for tmdb, phylm will first perform a search based on the ID. If the ID is valid the result will be selected, if not then it will fall back to a title search.
Alternatively, you can pass it to load_source with "tmdb" as the first argument:
await phylm.load_source("tmdb", tmdb_id="609")
+Or instantiate the TMDB source class with the ID:
from phylm.sources import Tmdb
+
+tmdb = Tmdb(movie_id="0133093")
+If instantiating the class directly you must supply at least one of movie_id or raw_title, otherwise a ValueError will be raised.
Note that TMDB doesn't provide any fuzzy search for title, only exact matches are returned.
Reference¶
Class to abstract a TMDB result.
id: Optional[str] property ¶
Return the TMDB id.
Returns:
| Type | Description |
|---|---|
Optional[str] | the id of the movie |
imdb_id: Optional[str] property ¶
Return the IMDb id.
Returns:
| Type | Description |
|---|---|
Optional[str] | the IMDb id of the movie |
plot: Optional[str] property ¶
Return the plot.
Returns:
| Type | Description |
|---|---|
Optional[str] | the plot of the movie |
rating: Optional[float] property ¶
Return the TMDB rating.
Returns:
| Type | Description |
|---|---|
Optional[float] | the rating of the movie |
release_date: Optional[str] property ¶
Return the movie's release_date.
Returns:
| Type | Description |
|---|---|
Optional[str] | the release date of the movie |
runtime: Optional[int] property ¶
Return the runtime.
Returns:
| Type | Description |
|---|---|
Optional[int] | the runtime of the movie |
title: Optional[str] property ¶
Return the TMDB title.
Returns:
| Type | Description |
|---|---|
Optional[str] | the title of the movie |
year: Optional[int] property ¶
Return the movie's year.
Returns:
| Type | Description |
|---|---|
Optional[int] | the year the movie was made |
__init__(raw_title: Optional[str] = None, movie_id: Optional[str] = None, raw_year: Optional[int] = None, api_key: Optional[str] = None, session: Optional[ClientSession] = None) -> None ¶
Initialize the object.
Note that at least one of raw_title or movie_id must be given to be used as a search term. movie_id is preferred over raw_title.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
raw_title | Optional[str] | the title of the movie. Note that TMDB doesn't support fuzzy search. | None |
movie_id | Optional[str] | the TMDB id of the movie. | None |
raw_year | Optional[int] | an optional year for improved matching if only title is given. | None |
api_key | Optional[str] | a TMDB api key. Must be supplied here or as an env var | None |
session | Optional[ClientSession] | a | None |
Raises:
| Type | Description |
|---|---|
ValueError | if neither |
genres(limit: int = 3) -> List[str] ¶
Return the genres.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
limit | int | an optional number of genres to return | 3 |
Returns:
| Type | Description |
|---|---|
List[str] | a list of the movie's genres |
load_source(session: Optional[ClientSession] = None) -> None async ¶
Asynchronously load the data for from the source.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session | Optional[ClientSession] | an optional | None |
Last update: 2023-10-18
Tools
phylm also offers some tools and utilities related to movies.
Search movies¶
For a given movie title query you can return a list of search results from IMDb through search_movies:
>>> from phylm.tools import search_movies
+>>> search_movies("the matrix")
+[{
+ 'title': 'The Matrix',
+ 'kind': 'movie',
+ 'year': 1999,
+ 'cover_photo': 'https://some-url.com',
+ 'imdb_id': '0133093',
+}, {
+ 'title': 'The Matrix Reloaded',
+ 'kind': 'movie',
+ 'year': 2003,
+ 'cover_photo': 'https://some-url.com',
+ 'imdb_id': '0234215',
+}, {
+...
+ phylm.tools.search_movies(query: str) -> List[Dict[str, Union[str, int]]] ¶
Return a list of search results for a query.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query | str | the search query | required |
Returns:
| Type | Description |
|---|---|
List[Dict[str, Union[str, int]]] | a list of search results |
TMDB¶
phylm also provides tools to interact with The Movie Database (TMDb).
To use TMDb tools you'll need to sign up for an API key, instructions here. Once you have your key, export it as an env var called TMDB_API_KEY so that it's available to use in these tools. You also have the option of passing in the key as an argument to each function.
Search movies¶
For a given movie title query you can return a list of search results from TMDb through search_tmdb_movies. Note that this search performs a lot quicker than the imdb search_movies.
>>> from phylm.tools import search_tmdb_movies
+>>> search_tmdb_movies("The Matrix", api_key="abc") # the api key can be provided as an env var instead
+[{
+ 'adult': False,
+ 'backdrop_path': '/fNG7i7RqMErkcqhohV2a6cV1Ehy.jpg',
+ 'genre_ids': [28, 878],
+ 'id': 603,
+ 'original_language': 'en',
+ 'original_title': 'The Matrix',
+ 'overview': 'Set in the 22nd century, The Matrix tells the story of a computer hacker...'
+ 'popularity': 79.956,
+ 'poster_path': '/f89U3ADr1oiB1s9GkdPOEpXUk5H.jpg',
+ 'release_date': '1999-03-30',
+ 'title': 'The Matrix',
+ 'video': False,
+ 'vote_average': 8.2,
+ 'vote_count': 20216,
+}, {
+ ...
+}
+By default the release_date will be the US release date. You can specify a different region by providing a region argument:
>>> from phylm.tools import search_tmdb_movies
+>>> search_tmdb_movies("The Matrix", region="gb")
+[{
+ 'id': 603,
+ ...
+ 'release_date': '1999-06-11',
+ 'title': 'The Matrix',
+ ...
+}, {
+ ...
+}
+ phylm.tools.search_tmdb_movies(query: str, api_key: Optional[str] = None, region: Optional[str] = None) -> List[Dict[str, Any]] ¶
Search for movies on TMDb.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query | str | the query string | required |
api_key | Optional[str] | an api_key can either be provided here or through a TMDB_API_KEY env var | None |
region | Optional[str] | an optional region to provide with the search request, affects the release_date value returned, must be provided in ISO 3166-1 format (eg. "us" or "gb") | None |
Returns:
| Type | Description |
|---|---|
List[Dict[str, Any]] | List[Dict[str, Any]]: the search results |
Get streaming providers¶
For a given movie TMDb id and list of regions, you can return a list of streaming providers from TMDb via Just Watch through get_streaming_providers.
>>> from phylm.tools import get_streaming_providers
+>>> get_streaming_providers(tmdb_movie_id="438631", regions=["gb"], api_key="abc")
+{
+ 'gb': {
+ 'link': 'https://www.themoviedb.org/movie/438631-dune/watch?locale=GB',
+ 'rent': [{
+ 'display_priority': 8,
+ 'logo_path': '/pZgeSWpfvD59x6sY6stT5c6uc2h.jpg',
+ 'provider_id': 130,
+ 'provider_name': 'Sky Store',
+ }],
+ },
+}
+Consult the TMDb docs for more information on the data that's returned.
phylm.tools.get_streaming_providers(tmdb_movie_id: str, regions: List[str], api_key: Optional[str] = None) -> Dict[str, Any] ¶
Return a list of streaming providers for a given movie.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tmdb_movie_id | str | the tmdb id of the movie | required |
regions | List[str] | a list of regions to trim down the return list | required |
api_key | Optional[str] | an api_key can either be provided here or through a TMDB_API_KEY env var | None |
Returns:
| Type | Description |
|---|---|
Dict[str, Any] | Dict[str, Any]: a dictionary of streaming providers, keyed by region name |
Last update: 2023-10-18