Initial implementation of "popular" function

Docstrings and unit tests are still missing.

Author: Electronic-Mango

src/simplejustwatchapi/__init__.py

@@ -3,6 +3,7 @@
 from simplejustwatchapi.justwatch import details as details
 from simplejustwatchapi.justwatch import episodes as episodes
 from simplejustwatchapi.justwatch import offers_for_countries as offers_for_countries
+from simplejustwatchapi.justwatch import popular as popular
 from simplejustwatchapi.justwatch import search as search
 from simplejustwatchapi.justwatch import seasons as seasons
 from simplejustwatchapi.tuples import Episode as Episode
@@ -24,6 +25,7 @@
     "details",
     "episodes",
     "offers_for_countries",
+    "popular",
     "search",
     "seasons",
 ]

src/simplejustwatchapi/graphql.py

@@ -44,6 +44,39 @@
 }
 """
 
+_GRAPHQL_POPULAR_QUERY = """
+query GetPopularTitles(
+  $popularTitlesFilter: TitleFilter
+  $country: Country!
+  $language: Language!
+  $first: Int! = 70
+  $formatPoster: ImageFormat,
+  $formatOfferIcon: ImageFormat,
+  $profile: PosterProfile
+  $backdropProfile: BackdropProfile,
+  $filter: OfferFilter!,
+  $offset: Int = 0
+) {
+  popularTitles(
+    country: $country
+    filter: $popularTitlesFilter
+    first: $first
+    sortBy: POPULAR
+    sortRandomSeed: 0
+    offset: $offset
+  ) {
+    __typename
+    edges {
+      node {
+        ...TitleDetails
+        __typename
+      }
+      __typename
+    }
+  }
+}
+"""
+
 _GRAPHQL_DETAILS_QUERY = """
 query GetTitleNode(
   $nodeId: ID!,
@@ -274,6 +307,10 @@ def graphql_search_query() -> str:
     return _GRAPHQL_SEARCH_QUERY + _GRAPHQL_DETAILS_FRAGMENT + _GRAPHQL_OFFER_FRAGMENT
 
 
+def graphql_popular_query() -> str:
+    return _GRAPHQL_POPULAR_QUERY + _GRAPHQL_DETAILS_FRAGMENT + _GRAPHQL_OFFER_FRAGMENT
+
+
 def graphql_details_query() -> str:
     """
     Prepare GraphQL query used for getting details regarding a single entry.

src/simplejustwatchapi/justwatch.py

@@ -6,11 +6,13 @@
     parse_details_response,
     parse_episodes_response,
     parse_offers_for_countries_response,
+    parse_popular_response,
     parse_search_response,
     parse_seasons_response,
     prepare_details_request,
     prepare_episodes_request,
     prepare_offers_for_countries_request,
+    prepare_popular_request,
     prepare_search_request,
     prepare_seasons_request,
 )
@@ -66,6 +68,20 @@ def search(
     return parse_search_response(response.json())
 
 
+def popular(
+    country: str = "US",
+    language: str = "en",
+    count: int = 4,
+    best_only: bool = True,
+    offset: int = 0,
+    providers: list[str] | str | None = None,
+) -> list[MediaEntry]:
+    request = prepare_popular_request(country, language, count, best_only, offset, providers)
+    response = post(_GRAPHQL_API_URL, json=request)
+    response.raise_for_status()
+    return parse_popular_response(response.json())
+
+
 def details(
     node_id: str,
     country: str = "US",

src/simplejustwatchapi/query.py

@@ -10,6 +10,7 @@
     graphql_details_query,
     graphql_episodes_query,
     graphql_offers_for_countries_query,
+    graphql_popular_query,
     graphql_search_query,
     graphql_seasons_query,
 )
@@ -96,6 +97,37 @@ def parse_search_response(json: dict) -> list[MediaEntry]:
     return [_parse_entry(edge["node"]) for edge in json["data"]["popularTitles"]["edges"]]
 
 
+def prepare_popular_request(
+    country: str,
+    language: str,
+    count: int,
+    best_only: bool,
+    offset: int,
+    providers: list[str] | str | None,
+) -> dict:
+    _assert_country_code_is_valid(country)
+    return {
+        "operationName": "GetPopularTitles",
+        "variables": {
+            "first": count,
+            "popularTitlesFilter": {"packages": providers},
+            "language": language,
+            "country": country.upper(),
+            "formatPoster": "JPG",
+            "formatOfferIcon": "PNG",
+            "profile": "S718",
+            "backdropProfile": "S1920",
+            "filter": {"bestOnly": best_only},
+            "offset": offset or None,
+        },
+        "query": graphql_popular_query(),
+    }
+
+
+def parse_popular_response(json: dict) -> list[MediaEntry]:
+    return [_parse_entry(edge["node"]) for edge in json["data"]["popularTitles"]["edges"]]
+
+
 def prepare_details_request(node_id: str, country: str, language: str, best_only: bool) -> dict:
     """
     Prepare a details request for specified node ID to JustWatch GraphQL API.