Add "offset" parameter to "search"

"offset" allows skipping first "x" elements from search results.
It allows for getting more data from JustWatch, without creating a single large query.

Author: Electronic-Mango

pyproject.toml

@@ -61,6 +61,7 @@ ignore = [
   "D212",  # Conflicts with D213
   "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",

src/simplejustwatchapi/graphql.py

@@ -22,13 +22,15 @@
   $profile: PosterProfile,
   $backdropProfile: BackdropProfile,
   $filter: OfferFilter!,
+  $offset: Int = 0,
 ) {
   popularTitles(
     country: $country
     filter: $searchTitlesFilter
     first: $first
     sortBy: POPULAR
     sortRandomSeed: 0
+    offset: $offset
   ) {
     edges {
       node {

src/simplejustwatchapi/justwatch.py

@@ -25,12 +25,22 @@ def search(
     language: str = "en",
     count: int = 4,
     best_only: bool = True,
+    offset: int = 0,
 ) -> list[MediaEntry]:
     """
     Search JustWatch for given title.
 
     Returns a list of entries up to ``count``.
 
+    ``offset`` specifies how many first entries should be skipped. This is done on API side,
+    not the library side; the returned list is still directly parsed from API response.
+    I'm not sure if it guarantees stability of results - whether repeated calls to this function
+    with increasing offset will guarantee that you won't get repeats.
+
+    JustWatch API won't allow for getting more than 2000 responses, either through ``count``, or
+    when ``count + offset`` is equal or greater than 2000 - it will return an empty list instead
+    (ALWAYS an empty list, if ``offset`` is lower than 2000 it won't include entries up to 2000).
+
     ``best_only`` allows filtering out redundant offers, e.g. when service provides offers
     in 4K, HD and SD, using ``best_only = True`` returns only 4K option, ``best_only = False``
     returns all three.
@@ -41,6 +51,7 @@ def search(
         language (str): Language of responses, ``en`` by default.
         count (int): How many responses should be returned.
         best_only (bool): Return only best offers if ``True``, return all offers if ``False``.
+        offset (int): Search results offset.
 
     Returns:
         list[MediaEntry]: List of ``MediaEntry`` NamedTuples parsed from JustWatch response.
@@ -49,7 +60,7 @@ def search(
         httpx.HTTPStatusError: If JustWatch API doesn't respond with success code.
 
     """
-    request = prepare_search_request(title, country, language, count, best_only)
+    request = prepare_search_request(title, country, language, count, best_only, offset)
     response = post(_GRAPHQL_API_URL, json=request)
     response.raise_for_status()
     return parse_search_response(response.json())

src/simplejustwatchapi/query.py

@@ -34,6 +34,7 @@ def prepare_search_request(
     language: str,
     count: int,
     best_only: bool,
+    offset: int,
 ) -> dict:
     """
     Prepare search request for JustWatch GraphQL API.
@@ -50,6 +51,7 @@ def prepare_search_request(
         language (str): Language of responses.
         count (int): How many responses should be returned.
         best_only (bool): Return only best offers if ``True``, return all offers if ``False``.
+        offset (int): Search results offset.
 
     Returns:
         dict: JSON/dict with GraphQL POST body.
@@ -68,6 +70,7 @@ def prepare_search_request(
             "profile": "S718",
             "backdropProfile": "S1920",
             "filter": {"bestOnly": best_only},
+            "offset": offset or None,
         },
         "query": graphql_search_query(),
     }

test/simplejustwatchapi/test_graphql.py

@@ -19,13 +19,15 @@
   $profile: PosterProfile,
   $backdropProfile: BackdropProfile,
   $filter: OfferFilter!,
+  $offset: Int = 0,
 ) {
   popularTitles(
     country: $country
     filter: $searchTitlesFilter
     first: $first
     sortBy: POPULAR
     sortRandomSeed: 0
+    offset: $offset
   ) {
     edges {
       node {

test/simplejustwatchapi/test_justwatch.py

@@ -6,7 +6,7 @@
 
 JUSTWATCH_GRAPHQL_URL = "https://apis.justwatch.com/graphql"
 
-SEARCH_INPUT = ("TITLE", "COUNTRY", "LANGUAGE", 5, True)
+SEARCH_INPUT = ("TITLE", "COUNTRY", "LANGUAGE", 5, True, 10)
 DETAILS_INPUT = ("NODE ID", "COUNTRY", "LANGUAGE", False)
 OFFERS_COUNTRIES_INPUT = {"COUNTRY1", "COUNTRY2", "COUNTRY3"}
 OFFERS_INPUT = ("NODE ID", OFFERS_COUNTRIES_INPUT, "LANGUAGE", True)

test/simplejustwatchapi/test_request.py

@@ -20,10 +20,10 @@
 
 @patch("simplejustwatchapi.query.graphql_search_query", return_value=DUMMY_SEARCH_QUERY)
 @mark.parametrize(
-    argnames=("title", "country", "language", "count", "best_only"),
+    argnames=("title", "country", "language", "count", "best_only", "offset"),
     argvalues=[
-        ("TITLE 1", "US", "language 1", 5, True),
-        ("TITLE 2", "gb", "language 2", 10, False),
+        ("TITLE 1", "US", "language 1", 5, True, 0),
+        ("TITLE 2", "gb", "language 2", 10, False, 20),
     ],
 )
 def test_prepare_search_request(
@@ -33,6 +33,7 @@ def test_prepare_search_request(
     language: str,
     count: int,
     best_only: bool,
+    offset: int,
 ):
     expected_request = {
         "operationName": "GetSearchTitles",
@@ -46,10 +47,11 @@ def test_prepare_search_request(
             "profile": "S718",
             "backdropProfile": "S1920",
             "filter": {"bestOnly": best_only},
+            "offset": offset or None,
         },
         "query": DUMMY_SEARCH_QUERY,
     }
-    request = prepare_search_request(title, country, language, count, best_only)
+    request = prepare_search_request(title, country, language, count, best_only, offset)
     assert expected_request == request
 
 
@@ -67,7 +69,7 @@ def test_prepare_search_request_asserts_on_invalid_country_code(
 ):
     expected_error_message = f"Invalid country code: {invalid_code}, code must be 2 characters long"
     with raises(AssertionError) as error:
-        prepare_search_request("", invalid_code, "", 1, True)
+        prepare_search_request("", invalid_code, "", 1, True, 2)
     assert str(error.value) == expected_error_message
     query_mock.assert_not_called()