Add docstrings to all fields in query tuples, tweak existing docstrings

Author: Electronic-Mango

src/simplejustwatchapi/justwatch.py

@@ -1,12 +1,4 @@
-"""Main module orchestrating requests to JustWatch GraphQL API.
-Currently supported requests are:
-
- - ``search`` - search for entries via title
- - ``details`` - get details for given node ID
- - ``offers_for_countries`` - get all offers for entry with given node ID,
-   can look for offers for multiple countries
-
-"""
+"""Main module orchestrating requests to JustWatch GraphQL API."""
 
 from httpx import post
 
@@ -28,7 +20,9 @@ def search(
     title: str, country: str = "US", language: str = "en", count: int = 4, best_only: bool = True
 ) -> list[MediaEntry]:
     """Search JustWatch for given title.
+
     Returns a list of entries up to ``count``.
+
     ``best_only`` allows filtering out redundant offers, e.g. when if provide offers service
     in 4K, HD and SD, using ``best_only = True`` returns only 4K option, ``best_only = False``
     returns all three.
@@ -53,6 +47,7 @@ def details(
     node_id: str, country: str = "US", language: str = "en", best_only: bool = True
 ) -> MediaEntry:
     """Get details of entry for a given ID.
+
     ``best_only`` allows filtering out redundant offers, e.g. when if provide offers service
     in 4K, HD and SD, using ``best_only = True`` returns only 4K option, ``best_only = False``
     returns all three.
@@ -79,7 +74,7 @@ def offers_for_countries(
     Language argument only specifies format of price string, e.g. whether ".", or "," is used
     in decimal fractions.
 
-    Returned dict has keys matching "countries" argument and values are list of found offers.
+    Returned dict has keys matching ``countries`` argument and values are list of found offers.
     If no countries are passed (an empty set given as argument) empty dict is returned.
 
     Country codes passed as argument are case-insensitive, however keys in returned dict will match

src/simplejustwatchapi/query.py

@@ -1,12 +1,5 @@
 """Module responsible for creating GraphQL queries and parsing responses from JustWatch GraphQL API.
-Parsed responses are returned as Python NamedTuples for easier access.
-Currently supported queries are:
-
- - ``GetTitleNode``
- - ``GetSearchTitles``
- - ``GetTitleOffers``
-
-"""
+Parsed responses are returned as Python NamedTuples for easier access."""
 
 from typing import NamedTuple
 
@@ -158,61 +151,134 @@ class OfferPackage(NamedTuple):
     Contains information about platform on which given offer is available."""
 
     id: str
+    """ID, defines whole platform on which this offer is available, not a single offer."""
+
     package_id: int
+    """Package ID, defines whole platform on which this offer is available, not a single offer."""
+
     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."""
+
     icon: str
+    """Platform icon URL."""
 
 
 class Offer(NamedTuple):
     """Parsed single offer from JustWatch GraphQL API for single entry.
     One platform can have multiple offers for one entry available, e.g. renting, buying, etc."""
 
     id: str
+    """Offer ID."""
+
     monetization_type: str
+    """Type of monetization of this offer, e.g. ``FLATRATE`` (streaming), ``RENT``, ``BUY``."""
+
     presentation_type: str
+    """Quality of media in this offer, e.g. ``HD``, ``SD``, ``4K``."""
+
     price_string: str | None
+    """Current price as a string with currency, suitable for displaying to users.
+    Format can change based on used ``language`` argument."""
+
     price_value: float | None
+    """Current price as a numeric value."""
+
     price_currency: str
+    """Represents only currency, without price, or value."""
+
     last_change_retail_price_value: float | None
+    """Previous available price if change in price was recorded."""
+
     type: str
+    """Type of offer."""
+
     package: OfferPackage
+    """Information about platform on which this offer is available."""
+
     url: str
+    """URL to this offer."""
+
     element_count: int
+    """Element count, usually 0."""
+
     available_to: str | None
+    """Date until which this offer will be available."""
+
     deeplink_roku: str | None
+    """Deeplink to this offer in Roku."""
+
     subtitle_languages: list[str]
+    """List of 2-letter language codes of available subtitles, e.g. ``["en", "pt", "de"]``."""
+
     video_technology: list[str]
+    """List of known video technologies available in this offer, e.g. ``DOLBY_VISION``."""
+
     audio_technology: list[str]
+    """List of known audio technologies available in this offer, e.g. ``DOLBY_ATMOS``."""
+
     audio_languages: list[str]
+    """List of 2-letter language codes of available audio tracks, e.g. ``["en", "pt", "de"]``."""
 
 
 class MediaEntry(NamedTuple):
     """Parsed response from JustWatch GraphQL API for "GetSearchTitles" query for single entry."""
 
     entry_id: str
+    """Entry ID, contains type code and numeric ID."""
+
     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."""
+
     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."""
+
     short_description: str
+    """Short description of this entry."""
+
     genres: list[str]
+    """List of genre codes for this entry, e.g. ``["rly"]``, ``["cmy", "drm", "rma"]``."""
+
     imdb_id: str | None
+    """ID of this entry in IMDB."""
+
     poster: str | None
+    """URL to poster for this ID."""
+
     backdrops: list[str]
+    """List of URLs for backdrops (full screen images to use as background)."""
+
     offers: list[Offer]
+    """List of available offers for this entry, empty if there are no available offers."""
 
 
 def prepare_search_request(
     title: str, country: str, language: str, count: int, best_only: bool
 ) -> dict:
     """Prepare search request for JustWatch GraphQL API.
     Creates a ``GetSearchTitles`` 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_search_response`.
+
     Args:
         title: title to search
         country: country to search for offers
@@ -244,8 +310,11 @@ def prepare_search_request(
 def parse_search_response(json: dict) -> list[MediaEntry]:
     """Parse response from search query from JustWatch GraphQL API.
     Parses response for ``GetSearchTitles`` query.
+
     If API didn't return any data, then an empty list is returned.
 
+    Meant to be used together with :func:`prepare_search_request`.
+
     Args:
         json: JSON returned by JustWatch GraphQL API
 
@@ -258,8 +327,11 @@ def parse_search_response(json: dict) -> list[MediaEntry]:
 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.
     Creates a ``GetTitleNode`` 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_details_response`.
+
     Args:
         node_id: node ID of entry to get details for
         country: country to search for offers
@@ -289,9 +361,12 @@ def prepare_details_request(node_id: str, country: str, language: str, best_only
 def parse_details_response(json: any) -> MediaEntry | None:
     """Parse response from details query from JustWatch GraphQL API.
     Parses response for ``GetTitleNode`` query.
+
     If API responded with an internal error (mostly due to not found node ID),
     then ``None`` will be returned instead.
 
+    Meant to be used together with :func:`prepare_details_request`.
+
     Args:
         json: JSON returned by JustWatch GraphQL API
 
@@ -308,9 +383,12 @@ def prepare_offers_for_countries_request(
     """Prepare an offers request for specified node ID and for all specified countries
     to JustWatch GraphQL API.
     Creates a ``GetTitleOffers`` GraphQL query.
+
     Country codes should be two uppercase letters, however they will be auto-converted to uppercase.
     ``countries`` argument mustn't be empty.
 
+    Meant to be used together with :func:`parse_offers_for_countries_response`.
+
     Args:
         node_id: node ID of entry to get details for
         countries: list of country codes to search for offers
@@ -341,11 +419,14 @@ def prepare_offers_for_countries_request(
 def parse_offers_for_countries_response(json: any, countries: set[str]) -> dict[str, list[Offer]]:
     """Parse response from offers query from JustWatch GraphQL API.
     Parses response for ``GetTitleOffers`` query.
+
     Response if searched for country codes passed as ``countries`` argument.
     Countries in JSON response which are not present in ``countries`` set will be ignored.
     If response doesn't have offers for a country, then that country still will be present
     in returned dict, just with an empty list as value.
 
+    Meant to be used together with :func:`prepare_offers_for_countries_request`.
+
     Args:
         json: JSON returned by JustWatch GraphQL API
         countries: set of countries to look for in API response