simple-justwatch-python-api 1.1.0__tar.gz → 1.3.0__tar.gz

{simple_justwatch_python_api-1.1.0 → simple_justwatch_python_api-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simple-justwatch-python-api
-Version: 1.1.0
+Version: 1.3.0
 Summary: A simple JustWatch Python API
 Keywords: justwatch,api,graphql
 Author: Electronic Mango

{simple_justwatch_python_api-1.1.0 → simple_justwatch_python_api-1.3.0}/pyproject.toml

@@ -3,7 +3,7 @@ name = "simple-justwatch-python-api"
 authors = [
     { name = "Electronic Mango", email = "78230210+Electronic-Mango@users.noreply.github.com" },
 ]
-version = "1.1.0"
+version = "1.3.0"
 description = "A simple JustWatch Python API"
 readme = "README.md"
 license = "MIT"
@@ -30,7 +30,7 @@ dev = [
     "pytest>=9.0.3",
     "pytest-mock>=3.15.1",
     "ruff>=0.15.10",
-    "zensical>=0.0.32",
+    "zensical>=0.0.37",
 ]
 
 [project.urls]

{simple_justwatch_python_api-1.1.0 → simple_justwatch_python_api-1.3.0}/src/simplejustwatchapi/exceptions.py

@@ -40,4 +40,15 @@ class JustWatchHttpError(JustWatchError):
 
     This is a general exception for any HTTP-related errors, such as non-`2xx` status
     codes, network errors, timeouts, etc.
+
+    Attributes:
+        msg (str): Error message describing the HTTP error.
+        response (str | None): Optional text of the HTTP response, if available.
+            Usucally contains JSON with error responses from the API.
+
     """
+
+    def __init__(self, msg: str, response: str | None = None) -> None:
+        """Init JustWatchHttpError with error message and optional response text."""
+        super().__init__(msg)
+        self.response = response

{simple_justwatch_python_api-1.1.0 → simple_justwatch_python_api-1.3.0}/src/simplejustwatchapi/justwatch.py

@@ -9,11 +9,11 @@ prepared GraphQL query.
 Most functions have a number of common arguments (in addition to function-specific
 ones, like `title` to search for):
 
-| Name        | Description |
-|-------------|-------------|
-| `country`   | 2-letter country code for which offers are selected, (e.g., `US`, \
+| Name | Description |
+|------|-------------|
+| `country` | 2-letter country code for which offers are selected, (e.g., `US`, \
                 `GB`, `DE`). |
-| `language`  | Code for language in responses. It consists of 2 lowercase letters \
+| `language` | Code for language in responses. It consists of 2 lowercase letters \
                 with optional uppercase alphanumeric suffix (e.g., `en`, `en-US`, \
                 `de`, `de-CH1901`). |
 | `best_only` | Whether to return only "best" offers for each provider instead of, \
@@ -22,19 +22,23 @@ ones, like `title` to search for):
 Functions returning data for multiple titles
 ([`search`][simplejustwatchapi.justwatch.search],
 [`popular`][simplejustwatchapi.justwatch.popular])
-also allow for specifying number of elements, basic pagination, and filtering for
-specific providers:
+also allow for specifying number of elements, basic pagination, and additional
+filtering:
 
-| Name        | Description |
-|-------------|-------------|
-| `count`     | How many entries should be returned. |
-| `offset`    | Basic "pagination". Offset for the first returned result, i.e. how \
+| Name | Description |
+|------|-------------|
+| `count` | How many entries should be returned. |
+| `offset` | Basic "pagination". Offset for the first returned result, i.e. how \
                 many first entries should be skipped. Everything is handled on API \
                 side, this library isn't doing any filtering. |
 | `providers` | Providers (like Netflix, Amazon Prime Video) for which offers should \
                 returned. Requires 3-letter "short name". Check \
                 [`providers`][simplejustwatchapi.justwatch.providers] for an example \
-                of how you can get that value.
+                of how you can get that value. |
+| `min_release_year` | Minimum release year of returned titles. |
+| `max_release_year` | Maximum release year of returned titles. |
+| `object_types` | Types of objects to filter for. It seems that only `SHOW` and \
+                   `MOVIE` are useful, but it's not strictly enforced. |
 
 Each function can raise two exceptions:
 
@@ -47,7 +51,7 @@ Each function can raise two exceptions:
     country code. |
 """
 
-from httpx import HTTPError, post
+from httpx import HTTPError, HTTPStatusError, post
 
 from simplejustwatchapi.exceptions import JustWatchHttpError
 from simplejustwatchapi.query import (
@@ -79,6 +83,9 @@ def search(
     best_only: bool = True,
     offset: int = 0,
     providers: list[str] | str | None = None,
+    min_release_year: int | None = None,
+    max_release_year: int | None = None,
+    object_types: list[str] | str | None = None,
 ) -> list[MediaEntry]:
     """
     Search JustWatch for the given title.
@@ -148,18 +155,50 @@ def search(
             You can look up values through [`providers`]
             [simplejustwatchapi.justwatch.providers] function.
 
+        min_release_year (int | None): Minimum release year of returned titles.
+
+            If `None` (the default value), no filtering is done.
+
+        max_release_year (int | None): Maximum release year of returned titles.
+
+            If `None` (the default value), no filtering is done.
+
+        object_types (list[str] | str | None): Types of objects to filter for, like
+            `SHOW` or `MOVIE`.
+
+            It seems that only `SHOW` and `MOVIE` are useful, but it's not strictly
+            enforced. Types like `SHOW_EPISODE`, or `SHOW_SEASON` can be used, but they
+            seem to return TV shows, same as `SHOW`.
+
+            While the type value is not enforced, it **must** be a valid type, otherwise
+            API will respond with HTTP status code 422.
+
+            For single type it can be a single string, or a list with one string.
+
+            If `None` (the default value), no filtering is done.
+
     Returns:
         (list[MediaEntry]): List of tuples with details of search results.
 
     Raises:
         exceptions.JustWatchApiError: JSON response from API has internal errors, e.g.,
             due to invalid language or country code.
+
         exceptions.JustWatchHttpError: HTTP error occurred, e.g., JustWatch API
             responded with non-`2xx` status code.
 
     """
     request = prepare_search_request(
-        title, country, language, count, best_only, offset, providers
+        title,
+        country,
+        language,
+        count,
+        best_only,
+        offset,
+        providers,
+        min_release_year,
+        max_release_year,
+        object_types,
     )
     response = _post_to_jw_graphql_api(request)
     return parse_search_response(response)
@@ -172,6 +211,9 @@ def popular(
     best_only: bool = True,
     offset: int = 0,
     providers: list[str] | str | None = None,
+    min_release_year: int | None = None,
+    max_release_year: int | None = None,
+    object_types: list[str] | str | None = None,
 ) -> list[MediaEntry]:
     """
     Look up all currently popular titles on JustWatch.
@@ -233,18 +275,47 @@ def popular(
             You can look up values through [`providers`]
             [simplejustwatchapi.justwatch.providers] function.
 
+        min_release_year (int | None): Minimum release year of returned titles.
+            If `None` (the default value), no filtering is done.
+
+        max_release_year (int | None): Maximum release year of returned titles.
+            If `None` (the default value), no filtering is done.
+
+        object_types (list[str] | str | None): Types of objects to filter for, like
+            `SHOW` or `MOVIE`.
+
+            It seems that only `SHOW` and `MOVIE` are useful, but it's not strictly
+            enforced. Types like `SHOW_EPISODE`, or `SHOW_SEASON` can be used, but they
+            seem to return TV shows, same as `SHOW`.
+
+            While the type value is not enforced, it **must** be a valid type, otherwise
+            API will respond with HTTP status code 422.
+
+            For single type it can be a single string, or a list with one string.
+
+            If `None` (the default value), no filtering is done.
+
     Returns:
         (list[MediaEntry]): List of tuples with details of popular titles.
 
     Raises:
         exceptions.JustWatchApiError: JSON response from API has internal errors, e.g.,
             due to invalid language or country code.
+
         exceptions.JustWatchHttpError: HTTP error occurred, e.g., JustWatch API
             responded with non-`2xx` status code.
 
     """
     request = prepare_popular_request(
-        country, language, count, best_only, offset, providers
+        country,
+        language,
+        count,
+        best_only,
+        offset,
+        providers,
+        min_release_year,
+        max_release_year,
+        object_types,
     )
     response = _post_to_jw_graphql_api(request)
     return parse_popular_response(response)
@@ -309,6 +380,7 @@ def details(
     Raises:
         exceptions.JustWatchApiError: JSON response from API has internal errors, e.g.,
             due to invalid language or country code.
+
         exceptions.JustWatchHttpError: HTTP error occurred, e.g., JustWatch API
             responded with non-`2xx` status code.
 
@@ -358,6 +430,7 @@ def seasons(
     Raises:
         exceptions.JustWatchApiError: JSON response from API has internal errors, e.g.,
             due to invalid language or country code.
+
         exceptions.JustWatchHttpError: HTTP error occurred, e.g., JustWatch API
             responded with non-`2xx` status code.
 
@@ -408,6 +481,7 @@ def episodes(
     Raises:
         exceptions.JustWatchApiError: JSON response from API has internal errors, e.g.,
             due to invalid language or country code.
+
         exceptions.JustWatchHttpError: HTTP error occurred, e.g., JustWatch API
             responded with non-`2xx` status code.
 
@@ -477,6 +551,7 @@ def offers_for_countries(
     Raises:
         exceptions.JustWatchApiError: JSON response from API has internal errors, e.g.,
             due to invalid language or country code.
+
         exceptions.JustWatchHttpError: HTTP error occurred, e.g., JustWatch API
             responded with non-`2xx` status code.
 
@@ -538,6 +613,8 @@ def _post_to_jw_graphql_api(request_json: dict) -> dict:
     try:
         response = post(_GRAPHQL_API_URL, json=request_json)
         response.raise_for_status()
+        return response.json()
+    except HTTPStatusError as e:
+        raise JustWatchHttpError(str(e), e.response.text) from e
     except HTTPError as e:
         raise JustWatchHttpError(str(e)) from e
-    return response.json()

{simple_justwatch_python_api-1.1.0 → simple_justwatch_python_api-1.3.0}/src/simplejustwatchapi/query.py

@@ -35,10 +35,6 @@ from simplejustwatchapi.tuples import (
 _DETAILS_URL = "https://justwatch.com"
 _IMAGES_URL = "https://images.justwatch.com"
 
-# TODO: Left here for posterity, remove once formats are well documented.
-_COUNTRY_CODE_REGEX = r"^[A-Z]{2}$"
-_LANGUAGE_CODE_REGEX = r"^[a-z]{2}(-[0-9A-Z]+)?$"
-
 
 def prepare_search_request(
     title: str,
@@ -48,6 +44,9 @@ def prepare_search_request(
     best_only: bool,
     offset: int,
     providers: list[str] | str | None,
+    min_release_year: int | None,
+    max_release_year: int | None,
+    object_types: list[str] | str | None,
 ) -> dict[str, Any]:
     """
     Prepare search request for JustWatch GraphQL API.
@@ -70,6 +69,10 @@ def prepare_search_request(
         offset (int): Search results offset.
         providers (list[str] | str | None): 3-letter service identifier(s),
             or `None` for all providers.
+        min_release_year (int | None): Minimum release year of returned titles.
+        max_release_year (int | None): Maximum release year of returned titles.
+        object_types (list[str] | str | None): Types of objects to filter for, it seems
+            that only "SHOW" and "MOVIE" make sense.
 
     Returns:
         (dict[str, Any]): JSON with GraphQL POST body.
@@ -79,7 +82,11 @@ def prepare_search_request(
         "operationName": "GetSearchTitles",
         "variables": {
             "first": count,
-            "searchTitlesFilter": {"searchQuery": title, "packages": providers},
+            "searchTitlesFilter": {
+                "searchQuery": title,
+                "packages": providers,
+                **_filter_variables(min_release_year, max_release_year, object_types),
+            },
             **_common_variables(best_only),
             **_locale_variables(country, language),
             "offset": offset or None,
@@ -122,6 +129,9 @@ def prepare_popular_request(
     best_only: bool,
     offset: int,
     providers: list[str] | str | None,
+    min_release_year: int | None,
+    max_release_year: int | None,
+    object_types: list[str] | str | None,
 ) -> dict[str, Any]:
     """
     Prepare "get popular" request for JustWatch GraphQL API.
@@ -143,6 +153,10 @@ def prepare_popular_request(
         offset (int): Search results offset.
         providers (list[str] | str | None): 3-letter service identifier(s),
             or `None` for all providers.
+        min_release_year (int | None): Minimum release year of returned titles.
+        max_release_year (int | None): Maximum release year of returned titles.
+        object_types (list[str] | str | None): Types of objects to filter for, it seems
+            that only "SHOW" and "MOVIE" make sense.
 
     Returns:
         (dict[str, Any]): JSON with GraphQL POST body.
@@ -152,7 +166,10 @@ def prepare_popular_request(
         "operationName": "GetPopularTitles",
         "variables": {
             "first": count,
-            "popularTitlesFilter": {"packages": providers},
+            "popularTitlesFilter": {
+                "packages": providers,
+                **_filter_variables(min_release_year, max_release_year, object_types),
+            },
             **_common_variables(best_only),
             **_locale_variables(country, language),
             "offset": offset or None,
@@ -511,6 +528,19 @@ def _locale_variables(country: str, language: str) -> dict[str, str]:
     return {"country": country.upper(), "language": language}
 
 
+def _filter_variables(
+    min_release_year: int | None,
+    max_release_year: int | None,
+    object_types: list[str] | str | None,
+) -> dict[str, Any]:
+    """Return dict with variables related to looking up lists of titles."""
+    return {
+        "includeTitlesWithoutUrl": True,
+        "objectTypes": object_types,
+        "releaseYear": {"min": min_release_year, "max": max_release_year},
+    }
+
+
 def _raise_for_errors_in_response(json: dict[str, Any]) -> None:
     """Raise JustWatchApiError if given JSON contains `errors` key."""
     if "errors" in json:

{simple_justwatch_python_api-1.1.0 → simple_justwatch_python_api-1.3.0}/src/simplejustwatchapi/tuples.py

@@ -222,7 +222,8 @@ class MediaEntry(NamedTuple):
         object_id (int): Object ID, the numeric part of full entry ID.
         object_type (str): Type of entry, e.g. `MOVIE`, `SHOW`.
         title (str): Full title.
-        url (str): URL to JustWatch with details for this entry.
+        url (str | None): URL to JustWatch with details for this entry. Some entries
+            are missing dedicated JustWatch pages, for them this field is `None`.
         release_year (int): Release year as a number.
         release_date (str): Full release date as a string, e.g. `2013-12-16`.
         runtime_minutes (int): Runtime in minutes.
@@ -255,7 +256,7 @@ class MediaEntry(NamedTuple):
     object_id: int
     object_type: str
     title: str
-    url: str
+    url: str | None
     release_year: int
     release_date: str
     runtime_minutes: int