simple-justwatch-python-api 0.19.0__tar.gz → 1.0.0__tar.gz

simple_justwatch_python_api-1.0.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: simple-justwatch-python-api
+Version: 1.0.0
+Summary: A simple JustWatch Python API
+Keywords: justwatch,api,graphql
+Author: Electronic Mango
+Author-email: Electronic Mango <78230210+Electronic-Mango@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: httpx>=0.28.1
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/Electronic-Mango/simple-justwatch-python-api
+Project-URL: Documentation, https://electronic-mango.github.io/simple-justwatch-python-api
+Project-URL: Repository, https://github.com/Electronic-Mango/simple-justwatch-python-api
+Project-URL: changelog, https://github.com/Electronic-Mango/simple-justwatch-python-api/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# Simple JustWatch Python API
+
+[![PyPi](https://img.shields.io/pypi/v/simple-justwatch-python-api.svg)](https://pypi.python.org/pypi/simple-justwatch-python-api)
+[![License](https://img.shields.io/pypi/l/simple-justwatch-python-api.svg)](https://pypi.python.org/pypi/simple-justwatch-python-api)
+[![Python versions](https://img.shields.io/pypi/pyversions/simple-justwatch-python-api.svg)](https://pypi.python.org/pypi/simple-justwatch-python-api)
+[![CodeQL](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/codeql.yml/badge.svg)](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/codeql.yml)
+[![Ruff](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/ruff.yml/badge.svg)](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/ruff.yml)
+[![Pytest](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/pytest.yml/badge.svg)](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/pytest.yml)
+[![Coverage Status](https://coveralls.io/repos/github/Electronic-Mango/simple-justwatch-python-api/badge.svg?branch=main)](https://coveralls.io/github/Electronic-Mango/simple-justwatch-python-api?branch=main)
+
+A simple unofficial JustWatch Python API which uses [`GraphQL`](https://graphql.org/)
+to access JustWatch data, available for Python `3.11+`.
+
+This project is managed by [uv](https://docs.astral.sh/uv/).
+
+
+
+## Installation
+
+This library is available through
+[PyPi](https://pypi.org/project/simple-justwatch-python-api/):
+```bash
+pip install simple-justwatch-python-api
+```
+
+
+## Documentation
+
+Detailed documentation is available at:
+<https://electronic-mango.github.io/simple-justwatch-python-api/>.
+
+
+
+## Highlights
+
+This Python library has multiple functions:
+
+ - `search` - search for entries based on title
+ - `popular` - get a list of currently popular titles
+ - `details` - get details for entry based on its node ID
+ - `seasons` - get information about all seasons of a show
+ - `episodes` - get information about all episodes of a season
+ - `offers_for_countries` - get offers for entry based on its node ID, can look for
+    offers in multiple countries
+ - `providers` - get data about available providers (e.g., Netflix)
+
+Example outputs from all functions are in [`examples/`](examples/) directory.
+
+
+
+## Quick example
+
+```python
+from simplejustwatchapi import search
+
+results = search("The Matrix", country="US", language="en", count=3)
+
+for entry in results:
+    print(entry.title, entry.object_type, len(entry.offers))
+```
+
+
+## License
+
+This library is licensed under **MIT license** ([LICENSE](./LICENSE) or
+<https://opensource.org/license/MIT>)
+
+
+
+## Disclaimer
+
+This library is in no way affiliated, associated, authorized, endorsed by, or in any way
+officially connected with JustWatch. This is an independent and unofficial project.
+
+Use at your own risk.

simple_justwatch_python_api-1.0.0/README.md

@@ -0,0 +1,75 @@
+# Simple JustWatch Python API
+
+[![PyPi](https://img.shields.io/pypi/v/simple-justwatch-python-api.svg)](https://pypi.python.org/pypi/simple-justwatch-python-api)
+[![License](https://img.shields.io/pypi/l/simple-justwatch-python-api.svg)](https://pypi.python.org/pypi/simple-justwatch-python-api)
+[![Python versions](https://img.shields.io/pypi/pyversions/simple-justwatch-python-api.svg)](https://pypi.python.org/pypi/simple-justwatch-python-api)
+[![CodeQL](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/codeql.yml/badge.svg)](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/codeql.yml)
+[![Ruff](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/ruff.yml/badge.svg)](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/ruff.yml)
+[![Pytest](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/pytest.yml/badge.svg)](https://github.com/Electronic-Mango/simple-justwatch-python-api/actions/workflows/pytest.yml)
+[![Coverage Status](https://coveralls.io/repos/github/Electronic-Mango/simple-justwatch-python-api/badge.svg?branch=main)](https://coveralls.io/github/Electronic-Mango/simple-justwatch-python-api?branch=main)
+
+A simple unofficial JustWatch Python API which uses [`GraphQL`](https://graphql.org/)
+to access JustWatch data, available for Python `3.11+`.
+
+This project is managed by [uv](https://docs.astral.sh/uv/).
+
+
+
+## Installation
+
+This library is available through
+[PyPi](https://pypi.org/project/simple-justwatch-python-api/):
+```bash
+pip install simple-justwatch-python-api
+```
+
+
+## Documentation
+
+Detailed documentation is available at:
+<https://electronic-mango.github.io/simple-justwatch-python-api/>.
+
+
+
+## Highlights
+
+This Python library has multiple functions:
+
+ - `search` - search for entries based on title
+ - `popular` - get a list of currently popular titles
+ - `details` - get details for entry based on its node ID
+ - `seasons` - get information about all seasons of a show
+ - `episodes` - get information about all episodes of a season
+ - `offers_for_countries` - get offers for entry based on its node ID, can look for
+    offers in multiple countries
+ - `providers` - get data about available providers (e.g., Netflix)
+
+Example outputs from all functions are in [`examples/`](examples/) directory.
+
+
+
+## Quick example
+
+```python
+from simplejustwatchapi import search
+
+results = search("The Matrix", country="US", language="en", count=3)
+
+for entry in results:
+    print(entry.title, entry.object_type, len(entry.offers))
+```
+
+
+## License
+
+This library is licensed under **MIT license** ([LICENSE](./LICENSE) or
+<https://opensource.org/license/MIT>)
+
+
+
+## Disclaimer
+
+This library is in no way affiliated, associated, authorized, endorsed by, or in any way
+officially connected with JustWatch. This is an independent and unofficial project.
+
+Use at your own risk.

{simple_justwatch_python_api-0.19.0 → simple_justwatch_python_api-1.0.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 = "0.19.0"
+version = "1.0.0"
 description = "A simple JustWatch Python API"
 readme = "README.md"
 license = "MIT"
@@ -11,7 +11,7 @@ license-files = ["LICENSE"]
 requires-python = ">= 3.11"
 keywords = ["justwatch", "api", "graphql"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3 :: Only",
@@ -26,20 +26,21 @@ dependencies = ["httpx>=0.28.1"]
 
 [dependency-groups]
 dev = [
-    "pytest>=9.0.2",
+    "mkdocstrings-python>=2.0.3",
+    "pytest>=9.0.3",
     "pytest-mock>=3.15.1",
-    "ruff>=0.15.8",
-    "sphinx>=9.0.4",
-    "sphinx-rtd-theme>=3.1.0",
+    "ruff>=0.15.10",
+    "zensical>=0.0.32",
 ]
 
 [project.urls]
 Homepage = "https://github.com/Electronic-Mango/simple-justwatch-python-api"
 Documentation = "https://electronic-mango.github.io/simple-justwatch-python-api"
 Repository = "https://github.com/Electronic-Mango/simple-justwatch-python-api"
+changelog = "https://github.com/Electronic-Mango/simple-justwatch-python-api/blob/main/CHANGELOG.md"
 
 [build-system]
-requires = ["uv_build>=0.11.2,<0.12"]
+requires = ["uv_build>=0.11.3,<0.12"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]
@@ -48,11 +49,7 @@ module-name = "simplejustwatchapi"
 [tool.pytest.ini_options]
 pythonpath = ["src", "test"]
 
-[tool.ruff]
-line-length = 100
-
 [tool.ruff.lint]
-exclude = ["./examples/*", "./docs/*"]
 select = ["ALL"]
 ignore = [
     "ANN401",  # Type hinting JSONs is problematic
@@ -62,7 +59,6 @@ ignore = [
     "FBT",
     "FIX002",
     "PLR0913", # I think it makes sense for functions here to have more arguments
-    "S101",    # Remove once asserts are converted to exceptions
     "TD002",
     "TD003",
 ]

simple_justwatch_python_api-1.0.0/src/simplejustwatchapi/__init__.py

@@ -0,0 +1,45 @@
+"""The main simplejustwatchapi package with "public" interface."""
+
+from simplejustwatchapi.exceptions import (
+    JustWatchApiError,
+    JustWatchError,
+    JustWatchHttpError,
+)
+from simplejustwatchapi.justwatch import (
+    details,
+    episodes,
+    offers_for_countries,
+    popular,
+    providers,
+    search,
+    seasons,
+)
+from simplejustwatchapi.tuples import (
+    Episode,
+    Interactions,
+    MediaEntry,
+    Offer,
+    OfferPackage,
+    Scoring,
+    StreamingCharts,
+)
+
+__all__ = [
+    "Episode",
+    "Interactions",
+    "JustWatchApiError",
+    "JustWatchError",
+    "JustWatchHttpError",
+    "MediaEntry",
+    "Offer",
+    "OfferPackage",
+    "Scoring",
+    "StreamingCharts",
+    "details",
+    "episodes",
+    "offers_for_countries",
+    "popular",
+    "providers",
+    "search",
+    "seasons",
+]

simple_justwatch_python_api-1.0.0/src/simplejustwatchapi/exceptions.py

@@ -0,0 +1,60 @@
+"""
+Exceptions raised by this library.
+
+All exceptions inherit from [`JustWatchError`]
+[simplejustwatchapi.exceptions.JustWatchError] for easier catching.
+
+Specific exceptions are raised for non-`2xx` HTTP response status codes and GraphQL
+API response errors.
+
+Each exception includes relevant information for why it was raised, but not always in
+any particular parsed format. For example, [`JustWatchApiError`]
+[simplejustwatchapi.exceptions.JustWatchApiError] includes the list of errors from the
+API response, but stored as a `dict`/JSON, as it was received from the API.
+
+"""
+
+
+class JustWatchError(Exception):
+    """Common parent for all exceptions raised by this library."""
+
+
+class JustWatchApiError(JustWatchError):
+    """
+    Raised when JustWatch API returned errors in JSON response.
+
+    If this error is raised, then API responded with status code `2xx`, but there are
+    listed errors in the internal JSON response. It can happen for too high complexity
+    of request, invalid node ID in functions like [`details`]
+    [simplejustwatchapi.justwatch.details], or invalid country or language codes.
+
+    Attributes:
+        errors (list[dict]): List of all errors in the JSON response from the API.
+            The `dict` elements are themselves basic JSONs, each with at least two
+            keys - `message` and `code`.
+
+    """
+
+    def __init__(self, errors: list[dict]) -> None:
+        """Init JustWatchApiError with internal errors from JSON response."""
+        super().__init__(f"Errors in JSON response: {errors}")
+        self.errors = errors
+
+
+class JustWatchHttpError(JustWatchError):
+    """
+    Raised when JustWatch API returned a non-`2xx` status code.
+
+    Any additional verification is not performed, ony the status code is checked.
+
+    Attributes:
+        code (int): HTTP status code returned by the API.
+        message (str): HTTP message response from the API.
+
+    """
+
+    def __init__(self, code: int, message: str) -> None:
+        """Init JustWatchHttpError with status code and message from response."""
+        super().__init__(f"HTTP code {code}: {message}")
+        self.code = code
+        self.message = message

{simple_justwatch_python_api-0.19.0 → simple_justwatch_python_api-1.0.0}/src/simplejustwatchapi/graphql.py

@@ -1,14 +1,16 @@
 """
 Module responsible for preparing full GraphQL queries.
 
-Queries are usually prepared as main query + details fragment + offers fragment.
+Queries are usually prepared as main query + needed fragments.
+Specific details are stored as separate GraphQL fragments / Python strings for easier
+reuse and maintainability.
 
 In the long term these queries should be moved to dedicated GraphQL resource files
-to allow for formatting and syntax checking. However, the functions used for constructing
-full queries shouldn't change.
+to allow for formatting and syntax checking. However, the functions used for
+constructing full queries shouldn't change.
 """
 
-# TODO: Convert these strings into resources, e.g.:
+# TODO: Convert these strings into resources, e.g.,:
 #       https://docs.python.org/3/library/importlib.resources.html
 
 _GRAPHQL_SEARCH_QUERY = """
@@ -322,10 +324,15 @@ def graphql_search_query() -> str:
     """
     Prepare GraphQL query used for searching for entries.
 
-    The query is GetSearchTitles query + details fragment + offers fragment + package fragment.
+    The full query is:
+
+      - `GetSearchTitles` query
+      - `TitleDetails` fragment
+      - `TitleOffer` fragment
+      - `PackageDetails` fragment
 
     Returns:
-        str: Full GraphQL "search" query.
+        (str): Full GraphQL `GetSearchTitles` query.
 
     """
     return (
@@ -340,10 +347,15 @@ def graphql_popular_query() -> str:
     """
     Prepare GraphQL query used for looking up currently popular titles.
 
-    The query is GetPopularTitles query + details fragment + offers fragment + package fragment.
+    The full query is:
+
+      - `GetPopularTitles` query
+      - `TitleDetails` fragment
+      - `TitleOffer` fragment
+      - `PackageDetails` fragment
 
     Returns:
-        str: Full GraphQL "popular" query.
+        (str): Full GraphQL `GetPopularTitles` query.
 
     """
     return (
@@ -358,10 +370,13 @@ def graphql_providers_query() -> str:
     """
     Prepare GraphQL query used for looking up all providers for a given country.
 
-    The query is GetProviders query + package fragment.
+    The full query is:
+
+      - `GetProviders` query
+      - `PackageDetails` fragment
 
     Returns:
-      str: Full GraphQL "providers" query.
+      (str): Full GraphQL `GetProviders` query.
 
     """
     return _GRAPHQL_PROVIDERS_QUERY + _GRAPHQL_PACKAGE_FRAGMENT
@@ -371,12 +386,18 @@ def graphql_details_query() -> str:
     """
     Prepare GraphQL query used for getting details regarding a single entry.
 
-    The full query is GetTitleNode query + details fragment + offers fragment  + package fragment.
+    The full query is:
+
+      - `GetTitleNode` query
+      - `TitleDetails` fragment
+      - `TitleOffer` fragment
+      - `PackageDetails` fragment
+
     It is meant for movies and shows, but can be used for seasons and episodes as well,
     it just won't return full season/episodes list.
 
     Returns:
-        str: Full GraphQL "get details" query.
+        (str): Full GraphQL `GetTitleNode` query.
 
     """
     return (
@@ -391,14 +412,20 @@ def graphql_seasons_query() -> str:
     """
     Prepare GraphQL query used for getting a list of seasons for a single show.
 
-    The full query is GetTitleNode query (with seasons list) + details fragment + offers fragment
-    + package fragment.
+    The full query is:
+
+      - `GetTitleNode` query, but only with a list of seasons
+      - `TitleDetails` fragment
+      - `TitleOffer` fragment
+      - `PackageDetails` fragment
+
     It will only return data for shows with a list of all available seasons, ascending.
-    Details query itself matches :func:`graphql_details_query`, its conditions will return all
+    `TitleDetails` query itself matches [`graphql_details_query`]
+    [simplejustwatchapi.graphql.graphql_details_query], its conditions will return all
     relevant data for seasons.
 
     Returns:
-        str: Full GraphQL "get seasons" query.
+        (str): GraphQL `GetTitleNode` query with a list of seasons.
 
     """
     return (
@@ -413,14 +440,20 @@ def graphql_episodes_query() -> str:
     """
     Prepare GraphQL query used for getting a list of episodes for a single show season.
 
-    The full query is GetTitleNode query (with episodes list) + details fragment + offers fragment
-    + package fragment.
-    It will only return data for show seasons with a list of all available episodes, ascending.
-    Details query itself matches :func:`graphql_details_query`, its conditions will return all
+    The full query is:
+
+      - `GetTitleNode` query, but only with a list of episodes
+      - `TitleDetails` fragment
+      - `TitleOffer` fragment
+      - `PackageDetails` fragment
+
+    It will only return data for show seasons with a list of all available episodes,
+    ascending. `TitleDetails` query itself matches [`graphql_details_query`]
+    [simplejustwatchapi.graphql.graphql_details_query], its conditions will return all
     relevant data for episodes.
 
     Returns:
-        str: Full GraphQL "get episodes" query.
+        (str): GraphQL `GetTitleNode` query with a list of episods.
 
     """
     return (
@@ -435,23 +468,25 @@ def graphql_offers_for_countries_query(countries: set[str]) -> str:
     """
     Prepare GraphQL query with a list of offers from specified countries.
 
-    The full query is GetTitleOffers query with a list of offers per country.
+    The full query is `GetTitleOffers` query with a list of offers per country.
     No additional information is returned, only offers.
     Can be used for all entry types - movies, shows, seasons, episodes.
 
-    The input is a set of 2-letter country codes. This function assumes that codes are valid length,
-    the set is not empty; it performs no additional verification.
+    The input is a set of 2-letter country codes. This function assumes that codes are
+    valid length and the set is not empty; it performs no verification on its own.
 
     Args:
         countries (set[str]): 2-letter country codes.
 
     Returns:
-        str: Full GraphQL "get offers per country" query.
+        (str): GraphQL `GetTitleOffers` query with available offers per country code.
 
     """
     offer_requests = [
         _GRAPHQL_COUNTRY_OFFERS_ENTRY.format(country_code=country_code.upper())
         for country_code in countries
     ]
-    main_query = _GRAPHQL_OFFERS_BY_COUNTRY_QUERY.format(country_entries="\n".join(offer_requests))
+    main_query = _GRAPHQL_OFFERS_BY_COUNTRY_QUERY.format(
+        country_entries="\n".join(offer_requests)
+    )
     return main_query + _GRAPHQL_OFFER_FRAGMENT + _GRAPHQL_PACKAGE_FRAGMENT