diff --git a/README.md b/README.md index 319a166..6f0571d 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,9 @@ +# Phylm + [![Actions Status](https://github.com/dbatten5/phylm/workflows/Tests/badge.svg)](https://github.com/dbatten5/phylm/actions) [![Actions Status](https://github.com/dbatten5/phylm/workflows/Release/badge.svg)](https://github.com/dbatten5/phylm/actions) [![codecov](https://codecov.io/gh/dbatten5/phylm/branch/master/graph/badge.svg?token=P233M48EA6)](https://codecov.io/gh/dbatten5/phylm) - -# Phylm +[![PyPI version](https://badge.fury.io/py/phylm.svg)](https://badge.fury.io/py/phylm) Film data aggregation. @@ -19,7 +20,7 @@ from various sources for a given film. pip install phylm ``` -# Usage +## Usage ```python >>> from phylm import Phylm @@ -31,6 +32,27 @@ pip install phylm 8.7 ``` +`phylm` also provides some tools around movie search results: + +```python +>>> from phylm.tools import search_movies +>>> search_movies("the matrix") +[{ + 'title': 'The Matrix', + 'kind': 'movie', + 'year': 1999, + 'cover url': 'https://some-url.com', + 'imdb_id': '0133093', +}, { + 'title': 'The Matrix Reloaded', + 'kind': 'movie', + 'year': 2003, + 'cover url': 'https://some-url.com', + 'imdb_id': '0234215', +}, { +... +``` + ## Help See the [documentation](https://dbatten5.github.io/phylm) for more details. diff --git a/docs/imdb.md b/docs/imdb.md index 70f6bba..4dc170a 100644 --- a/docs/imdb.md +++ b/docs/imdb.md @@ -19,4 +19,7 @@ imdb = Imdb(raw_title="The Matrix") ::: phylm.sources.imdb.Imdb rendering: - show_source: false + show_signature_annotations: true + heading_level: 2 + show_root_heading: false + show_root_toc_entry: false diff --git a/docs/index.md b/docs/index.md index d1b3c9c..f36690a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,7 +13,7 @@ class to gather information from various sources for a given film. pip install phylm ``` -# Usage +# Example ```python >>> from phylm import Phylm @@ -23,43 +23,6 @@ pip install phylm 8.7 ``` -The main entrypoint is the `Phylm` class. The class should be instantiated with -a `title` property. In order to access data from a source, you'll first need to -load the source. The available sources are: - -```python -"imdb" # IMDb -"rt" # Rotten Tomatoes -"mtc" # Metacritic -``` - -The source data can then be accessed through the following properties on a `Phylm` -instance: - -```python -phylm.imdb -phylm.rt -phylm.mtc -``` - !!! warning "" This package uses web scraping for the Rotten Tomatoes and Metacritic results and is therefore at the mercy of changes made to those webpages. - - -## 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 - - -```python -from phylm import Phylm -p = Phylm("Ambiguous Movie") # suppose this movie was released in 1999 -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" -``` diff --git a/docs/mtc.md b/docs/mtc.md index 4cc5b3a..e6d1e22 100644 --- a/docs/mtc.md +++ b/docs/mtc.md @@ -19,4 +19,7 @@ mtc = Mtc(raw_title="The Matrix") ::: phylm.sources.mtc.Mtc rendering: - show_source: false + show_signature_annotations: true + heading_level: 2 + show_root_heading: false + show_root_toc_entry: false diff --git a/docs/phylm.md b/docs/phylm.md index ac968d9..f403d3d 100644 --- a/docs/phylm.md +++ b/docs/phylm.md @@ -17,11 +17,38 @@ p.load_sources(["imdb", "rt"]) p.load_source("mtc") ``` -Now the source will be available through a property of the same name: +The available sources are: + +```python +"imdb" # IMDb +"rt" # Rotten Tomatoes +"mtc" # Metacritic +``` + +Now the source will be available through a property of the same name and datapoints on +that source can be accessed: ```python >>> p.imdb +>>> 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: + +```python +from phylm import Phylm +p = Phylm("Ambiguous Movie") # suppose this movie was released in 1999 +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. @@ -30,4 +57,7 @@ See the docs for a source for a full list of the available data points. ::: phylm.Phylm rendering: - show_source: true + show_signature_annotations: true + heading_level: 2 + show_root_heading: false + show_root_toc_entry: false diff --git a/docs/rt.md b/docs/rt.md index 6a8ae63..685ee47 100644 --- a/docs/rt.md +++ b/docs/rt.md @@ -19,4 +19,7 @@ rot_tom = Rt(raw_title="The Matrix") ::: phylm.sources.rt.Rt rendering: - show_source: false + show_signature_annotations: true + heading_level: 2 + show_root_heading: false + show_root_toc_entry: false diff --git a/docs/tools.md b/docs/tools.md new file mode 100644 index 0000000..226fb54 --- /dev/null +++ b/docs/tools.md @@ -0,0 +1,30 @@ +`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 `get_suggestions`: + +```python +>>> from phylm.tools import search_movies +>>> search_movies("the matrix") +[{ + 'title': 'The Matrix', + 'kind': 'movie', + 'year': 1999, + 'cover url': 'https://some-url.com', + 'imdb_id': '0133093', +}, { + 'title': 'The Matrix Reloaded', + 'kind': 'movie', + 'year': 2003, + 'cover url': 'https://some-url.com', + 'imdb_id': '0234215', +}, { +... +``` + +::: phylm.tools.search_movies + rendering: + show_signature_annotations: true + heading_level: 2 diff --git a/mkdocs.yml b/mkdocs.yml index 26c8cc0..affaf41 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,12 +13,13 @@ theme: nav: - Phylm: index.md - - Classes: + - Usage: - Phylm: phylm.md - Sources: IMDb: imdb.md Metacritic: mtc.md Rotten Tomatoes: rt.md + - Tools: tools.md - Contributing: contributing.md plugins: diff --git a/pyproject.toml b/pyproject.toml index d869ed4..78f2536 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "phylm" -version = "4.0.2" +version = "4.0.3" description = "Phylm" authors = ["Dom Batten "] license = "MIT" diff --git a/src/phylm/tools.py b/src/phylm/tools.py new file mode 100644 index 0000000..e599102 --- /dev/null +++ b/src/phylm/tools.py @@ -0,0 +1,22 @@ +"""Module to hold `phylm` tools.""" +from typing import Dict +from typing import List +from typing import Union + +from imdb.Movie import Movie + +from phylm.sources.imdb import ia + + +def search_movies(query: str) -> List[Dict[str, Union[str, int]]]: + """Return a list of search results for a query. + + Args: + query: the search query + + Returns: + a list of search results + """ + results: List[Movie] = ia.search_movie(query) + + return [{**r.data, "imdb_id": r.movieID} for r in results] diff --git a/tests/unit/tools/__init__.py b/tests/unit/tools/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/unit/tools/test_tools.py b/tests/unit/tools/test_tools.py new file mode 100644 index 0000000..74ec0c5 --- /dev/null +++ b/tests/unit/tools/test_tools.py @@ -0,0 +1,42 @@ +"""Tests for the `tools` module.""" +from typing import List +from unittest.mock import MagicMock +from unittest.mock import patch + +import pytest +from imdb import IMDb +from imdb.Movie import Movie + +from phylm.tools import search_movies + +ia = IMDb() + + +TOOLS_MODULE_PATH = "phylm.tools" + + +@pytest.fixture(scope="module", name="the_matrix") +def the_matrix_fixture() -> List[Movie]: + """Return The Matrix IMDb Movie object.""" + return list(ia.search_movie("The Matrix")) + + +class TestSearchMovies: + """Tests for the `search_movies` function.""" + + @patch(f"{TOOLS_MODULE_PATH}.ia", autospec=True) + def test_results(self, mock_ia: MagicMock, the_matrix: List[Movie]) -> None: + """ + Given a search query, + When the `search_movies` function is invoked with the query, + Then a list of search results is returned + """ + mock_ia.search_movie.return_value = the_matrix + + result: List[Movie] = search_movies("the matrix") + + assert len(result) + assert result[0]["imdb_id"] == "0133093" + assert result[0]["title"] == "The Matrix" + assert result[0]["year"] == 1999 + assert result[0]["cover url"]