Update docstrings

Author: Electronic-Mango

src/simplejustwatchapi/graphql.py

@@ -322,7 +322,7 @@ def graphql_search_query() -> str:
     """
     Prepare GraphQL query used for searching for entries.
 
-    The query is GetSearchTitles query + details fragment + offers fragment.
+    The query is GetSearchTitles query + details fragment + offers fragment + package fragment.
 
     Returns:
         str: Full GraphQL "search" query.
@@ -337,6 +337,15 @@ def graphql_search_query() -> str:
 
 
 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.
+
+    Returns:
+        str: Full GraphQL "popular" query.
+
+    """
     return (
         _GRAPHQL_POPULAR_QUERY
         + _GRAPHQL_DETAILS_FRAGMENT
@@ -346,14 +355,23 @@ def graphql_popular_query() -> str:
 
 
 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.
+
+    Returns:
+      str: Full GraphQL "providers" query.
+
+    """
     return _GRAPHQL_PROVIDERS_QUERY + _GRAPHQL_PACKAGE_FRAGMENT
 
 
 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.
+    The full query is GetTitleNode query + details fragment + offers fragment  + package 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.
 
@@ -373,7 +391,8 @@ 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.
+    The full query is GetTitleNode query (with seasons list) + details fragment + offers fragment
+    + package 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
     relevant data for seasons.
@@ -394,7 +413,8 @@ 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.
+    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
     relevant data for episodes.

src/simplejustwatchapi/justwatch.py

@@ -50,13 +50,22 @@ def search(
     in 4K, HD and SD, using ``best_only = True`` returns only 4K option, ``best_only = False``
     returns all three.
 
+    ``providers`` is a list of (usually) 3-letter service identifiers (e.g, ``nfx`` for "Netflix).
+    Only entries which are available for given providers will be returned.
+    For single provider you can either pass a single string, or a list of one string.
+    For ``None`` (also a default value) entries for all providers will be looked up.
+    Invalid names will be ignored, however if all are invalid, then no filtering will be done.
+    You can look up values through ``providers`` function.
+
     Args:
         title (str): Title to search.
         country (str): Country to search for offers, ``US`` by default.
         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.
+        providers (list[str] | str | None): 3-letter service identifier(s),
+            or ``None`` for all providers.
 
     Returns:
         list[MediaEntry]: List of ``MediaEntry`` NamedTuples parsed from JustWatch response.
@@ -79,6 +88,47 @@ def popular(
     offset: int = 0,
     providers: list[str] | str | None = None,
 ) -> list[MediaEntry]:
+    """
+    Look up all currently popular titles on JustWatch.
+
+    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.
+
+    ``providers`` is a list of (usually) 3-letter service identifiers (e.g, ``nfx`` for "Netflix).
+    Only entries which are available for given providers will be returned.
+    For single provider you can either pass a single string, or a list of one string.
+    For ``None`` (also a default value) entries for all providers will be looked up.
+    Invalid names will be ignored, however if all are invalid, then no filtering will be done.
+    You can look up values through ``providers`` function.
+
+    Args:
+        country (str): Country to search for offers, ``US`` by default.
+        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.
+        providers (list[str] | str | None): 3-letter service identifier(s),
+            or ``None`` for all providers.
+
+    Returns:
+        list[MediaEntry]: List of ``MediaEntry`` NamedTuples parsed from JustWatch response.
+
+    Raises:
+        httpx.HTTPStatusError: If JustWatch API doesn't respond with success code.
+
+    """
     request = prepare_popular_request(country, language, count, best_only, offset, providers)
     response = post(_GRAPHQL_API_URL, json=request)
     response.raise_for_status()
@@ -238,6 +288,18 @@ def offers_for_countries(
 
 
 def providers(country: str) -> list[OfferPackage]:
+    """
+    Look up all providers for the given country code.
+
+    Args:
+        country (str): 2-letter country code.
+
+    Returns:
+        list[OfferPackage]: List of all found providers. ``OfferPackage`` tuple matches
+            values in ``Offer`` (and thus in ``MediaEntry``), but the data structure is the same,
+            so the same tuple is reused.
+
+    """
     request = prepare_providers_request(country)
     response = post(_GRAPHQL_API_URL, json=request)
     response.raise_for_status()

src/simplejustwatchapi/query.py

@@ -55,6 +55,8 @@ def prepare_search_request(
         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.
+        providers (list[str] | str | None): 3-letter service identifier(s),
+            or ``None`` for all providers.
 
     Returns:
         dict: JSON/dict with GraphQL POST body.
@@ -107,6 +109,28 @@ def prepare_popular_request(
     offset: int,
     providers: list[str] | str | None,
 ) -> dict:
+    """
+    Prepare "get popular" request for JustWatch GraphQL API.
+
+    Creates a ``GetPopularTitles`` GraphQL query.
+
+    Country code should be two uppercase letters, however it will be auto-converted to uppercase.
+
+    Meant to be used together with :func:`parse_popular_response`.
+
+    Args:
+        country (str): Country to search for offers.
+        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.
+        providers (list[str] | str | None): 3-letter service identifier(s),
+            or ``None`` for all providers.
+
+    Returns:
+        dict: JSON/dict with GraphQL POST body.
+
+    """
     _assert_country_code_is_valid(country)
     return {
         "operationName": "GetPopularTitles",
@@ -127,6 +151,22 @@ def prepare_popular_request(
 
 
 def parse_popular_response(json: dict) -> list[MediaEntry]:
+    """
+    Parse response from the "get popular" query from JustWatch GraphQL API.
+
+    Parses response for ``GetPopularTitles`` query.
+
+    If API didn't return any data, then an empty list is returned.
+
+    Meant to be used together with :func:`prepare_popular_request`.
+
+    Args:
+        json (dict): JSON returned by JustWatch GraphQL API.
+
+    Returns:
+        list[MediaEntry]: Parsed received JSON as a list of ``MediaEntry`` NamedTuples.
+
+    """
     return [_parse_entry(edge["node"]) for edge in json["data"]["popularTitles"]["edges"]]
 
 
@@ -390,19 +430,50 @@ def parse_offers_for_countries_response(json: dict, countries: set[str]) -> dict
 
 
 def prepare_providers_request(country: str) -> dict:
+    """
+    Prepare "get all providers" request for JustWatch GraphQL API.
+
+    Creates a ``GetProviders`` GraphQL query.
+
+    Country code should be two uppercase letters, however it will be auto-converted to uppercase.
+
+    Meant to be used together with :func:`parse_providers_response`.
+
+    Args:
+        country (str): 2-letter country code for which providers should be looked up.
+
+    Returns:
+        dict: JSON/dict with GraphQL POST body.
+
+    """
     _assert_country_code_is_valid(country)
     return {
         "operationName": "GetProviders",
         "variables": {
             "country": country.upper(),
             "formatOfferIcon": "PNG",
-            "fullPath": "/us/tv-show/the-madison",
         },
         "query": graphql_providers_query(),
     }
 
 
 def parse_providers_response(json: dict) -> list[OfferPackage]:
+    """
+    Parse response from "get all providers" query from JustWatch GraphQL API.
+
+    Parses response for ``GetProviders`` query.
+
+    If API didn't return any data, then an empty list is returned.
+
+    Meant to be used together with :func:`prepare_providers_request`.
+
+    Args:
+        json (dict): JSON returned by JustWatch GraphQL API.
+
+    Returns:
+        list[MediaEntry]: Parsed received JSON as a list of ``OfferPackage`` NamedTuples.
+
+    """
     return [_parse_package(package) for package in json["data"]["packages"]]
 
 

src/simplejustwatchapi/tuples.py

@@ -16,6 +16,7 @@ class OfferPackage(NamedTuple):
         name (str): Name of the platform in format suited to display for users.
         technical_name (str): Technical name of the platform,
             usually all lowercase with no whitespaces.
+        short_name (str): 3-letter provider name.
         icon (str): Platform icon URL.
 
     """