Add raised exceptions to docstrings

src/simplejustwatchapi/justwatch.py

@@ -77,7 +77,9 @@ def search(
         list[MediaEntry]: List of ``MediaEntry`` NamedTuples parsed from JustWatch response.
 
     Raises:
-        httpx.HTTPStatusError: If JustWatch API doesn't respond with success code.
+        JustWatchHttpError: If JustWatch API doesn't respond with 2xx success code.
+        JustWatchCountryCodeError: Provided ``country`` is not a 2-letter code.
+        JustWatchApiError: Response from API has internal errors.
 
     """
     request = prepare_search_request(title, country, language, count, best_only, offset, providers)
@@ -134,7 +136,9 @@ def popular(
         list[MediaEntry]: List of ``MediaEntry`` NamedTuples parsed from JustWatch response.
 
     Raises:
-        httpx.HTTPStatusError: If JustWatch API doesn't respond with success code.
+        JustWatchHttpError: If JustWatch API doesn't respond with 2xx success code.
+        JustWatchCountryCodeError: Provided ``country`` is not a 2-letter code.
+        JustWatchApiError: Response from API has internal errors.
 
     """
     request = prepare_popular_request(country, language, count, best_only, offset, providers)
@@ -166,7 +170,9 @@ def details(
         MediaEntry: ``MediaEntry`` NamedTuple with data about requested entry.
 
     Raises:
-        httpx.HTTPStatusError: If JustWatch API doesn't respond with success code.
+        JustWatchHttpError: If JustWatch API doesn't respond with 2xx success code.
+        JustWatchCountryCodeError: Provided ``country`` is not a 2-letter code.
+        JustWatchApiError: Response from API has internal errors.
 
     """
     request = prepare_details_request(node_id, country, language, best_only)
@@ -195,7 +201,9 @@ def seasons(
         list[MediaEntry]: List of ``MediaEntry`` NamedTuples with data about requested entry.
 
     Raises:
-        httpx.HTTPStatusError: If JustWatch API doesn't respond with success code.
+        JustWatchHttpError: If JustWatch API doesn't respond with 2xx success code.
+        JustWatchCountryCodeError: Provided ``country`` is not a 2-letter code.
+        JustWatchApiError: Response from API has internal errors.
 
     """
     request = prepare_seasons_request(show_id, country, language, best_only)
@@ -224,7 +232,9 @@ def episodes(
         list[Episode]: List of ``Episode`` NamedTuples with data about requested entry.
 
     Raises:
-        httpx.HTTPStatusError: If JustWatch API doesn't respond with success code.
+        JustWatchHttpError: If JustWatch API doesn't respond with 2xx success code.
+        JustWatchCountryCodeError: Provided ``country`` is not a 2-letter code.
+        JustWatchApiError: Response from API has internal errors.
 
     """
     request = prepare_episodes_request(season_id, country, language, best_only)
@@ -281,7 +291,9 @@ def offers_for_countries(
         and keys are all found offers for their respective countries.
 
     Raises:
-        httpx.HTTPStatusError: If JustWatch API doesn't respond with success code.
+        JustWatchHttpError: If JustWatch API doesn't respond with 2xx success code.
+        JustWatchCountryCodeError: Provided ``countries`` contain invalid county code.
+        JustWatchApiError: Response from API has internal errors.
 
     """
     if not countries:
@@ -304,6 +316,11 @@ def providers(country: str = "US") -> list[OfferPackage]:
             values in ``Offer`` (and thus in ``MediaEntry``), but the data structure is the same,
             so the same tuple is reused.
 
+    Raises:
+        JustWatchHttpError: If JustWatch API doesn't respond with 2xx success code.
+        JustWatchCountryCodeError: Provided ``country`` is not a 2-letter code.
+        JustWatchApiError: Response from API has internal errors.
+
     """
     request = prepare_providers_request(country)
     response = post(_GRAPHQL_API_URL, json=request)

src/simplejustwatchapi/query.py

@@ -66,6 +66,9 @@ def prepare_search_request(
     Returns:
         dict: JSON/dict with GraphQL POST body.
 
+    Raises:
+        JustWatchCountryCodeError: Provided ``country`` is not a 2-letter code.
+
     """
     _raise_for_invalid_country_code(country)
     return {
@@ -102,6 +105,9 @@ def parse_search_response(json: dict) -> list[MediaEntry]:
     Returns:
         list[MediaEntry]: Parsed received JSON as a list of ``MediaEntry`` NamedTuples.
 
+    Raises:
+        JustWatchApiError: Response from API has internal errors.
+
     """
     _raise_for_errors_in_response(json)
     return [_parse_entry(edge["node"]) for edge in json["data"]["popularTitles"]["edges"]]
@@ -136,6 +142,9 @@ def prepare_popular_request(
     Returns:
         dict: JSON/dict with GraphQL POST body.
 
+    Raises:
+        JustWatchCountryCodeError: Provided ``country`` is not a 2-letter code.
+
     """
     _raise_for_invalid_country_code(country)
     return {
@@ -172,6 +181,9 @@ def parse_popular_response(json: dict) -> list[MediaEntry]:
     Returns:
         list[MediaEntry]: Parsed received JSON as a list of ``MediaEntry`` NamedTuples.
 
+    Raises:
+        JustWatchApiError: Response from API has internal errors.
+
     """
     _raise_for_errors_in_response(json)
     return [_parse_entry(edge["node"]) for edge in json["data"]["popularTitles"]["edges"]]
@@ -196,6 +208,9 @@ def prepare_details_request(node_id: str, country: str, language: str, best_only
     Returns:
         dict: JSON/dict with GraphQL POST body.
 
+    Raises:
+        JustWatchCountryCodeError: Provided ``country`` is not a 2-letter code.
+
     """
     _raise_for_invalid_country_code(country)
     return {
@@ -220,16 +235,16 @@ def parse_details_response(json: dict) -> MediaEntry:
 
     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 (dict): JSON returned by JustWatch GraphQL API.
 
     Returns:
-        MediaEntry | None: Parsed received JSON as a ``MediaEntry`` NamedTuple.
+        MediaEntry: Parsed received JSON as a ``MediaEntry`` NamedTuple.
+
+    Raises:
+        JustWatchApiError: Response from API has internal errors.
 
     """
     _raise_for_errors_in_response(json)
@@ -255,6 +270,9 @@ def prepare_seasons_request(show_id: str, country: str, language: str, best_only
     Returns:
         dict: JSON/dict with GraphQL POST body.
 
+    Raises:
+        JustWatchCountryCodeError: Provided ``country`` is not a 2-letter code.
+
     """
     _raise_for_invalid_country_code(country)
     return {
@@ -279,9 +297,6 @@ def parse_seasons_response(json: dict) -> list[MediaEntry]:
 
     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_seasons_request`.
 
     Args:
@@ -290,6 +305,9 @@ def parse_seasons_response(json: dict) -> list[MediaEntry]:
     Returns:
         list[MediaEntry]: Parsed received JSON as a ``MediaEntry`` NamedTuple list.
 
+    Raises:
+        JustWatchApiError: Response from API has internal errors.
+
     """
     _raise_for_errors_in_response(json)
     return [_parse_entry(season) for season in json["data"]["node"].get("seasons", [])]
@@ -314,6 +332,9 @@ def prepare_episodes_request(episode_id: str, country: str, language: str, best_
     Returns:
         dict: JSON/dict with GraphQL POST body.
 
+    Raises:
+        JustWatchCountryCodeError: Provided ``country`` is not a 2-letter code.
+
     """
     _raise_for_invalid_country_code(country)
     return {
@@ -338,9 +359,6 @@ def parse_episodes_response(json: dict) -> list[Episode]:
 
     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_episodes_request`.
 
     Args:
@@ -349,6 +367,9 @@ def parse_episodes_response(json: dict) -> list[Episode]:
     Returns:
         list[Episode]: Parsed received JSON as a ``Episode`` NamedTuple list.
 
+    Raises:
+        JustWatchApiError: Response from API has internal errors.
+
     """
     _raise_for_errors_in_response(json)
     return [_parse_episode(episode) for episode in json["data"]["node"].get("episodes", [])]
@@ -379,6 +400,9 @@ def prepare_offers_for_countries_request(
     Returns:
         dict: JSON/dict with GraphQL POST body.
 
+    Raises:
+        JustWatchCountryCodeError: Provided ``countries`` contain invalid country code.
+
     """
     if not countries:
         # This should never happen, justwatch.py should take care of this.
@@ -423,6 +447,9 @@ def parse_offers_for_countries_response(json: dict, countries: set[str]) -> dict
         dict[str, list[Offer]]: A dict, where keys are matching ``countries`` argument and values
         are offers for a given country parsed from JSON response.
 
+    Raises:
+        JustWatchApiError: Response from API has internal errors.
+
     """
     _raise_for_errors_in_response(json)
     return {
@@ -447,6 +474,9 @@ def prepare_providers_request(country: str) -> dict:
     Returns:
         dict: JSON/dict with GraphQL POST body.
 
+    Raises:
+        JustWatchCountryCodeError: Provided ``country`` is not a 2-letter code.
+
     """
     _raise_for_invalid_country_code(country)
     return {
@@ -475,6 +505,9 @@ def parse_providers_response(json: dict) -> list[OfferPackage]:
     Returns:
         list[MediaEntry]: Parsed received JSON as a list of ``OfferPackage`` NamedTuples.
 
+    Raises:
+        JustWatchApiError: Response from API has internal errors.
+
     """
     _raise_for_errors_in_response(json)
     return [_parse_package(package) for package in json["data"]["packages"]]