Merge pull request #20 from dbatten5/search-movies

Search movies

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.

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

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"
-```

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

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
 <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:
+
+```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

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

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

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:

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "phylm"
-version = "4.0.2"
+version = "4.0.3"
 description = "Phylm"
 authors = ["Dom Batten <[email protected]>"]
 license = "MIT"

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]

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"]