Tweak docs

Author: Electronic-Mango

docs/caveats.md

@@ -10,8 +10,7 @@ icon: lucide/notebook-pen
 
 The main structure [`MediaEntry`][simplejustwatchapi.tuples.MediaEntry] contains fields
 for all media types - movies, shows, seasons, episodes. Some fields are specific for one
-of the media types and will be
-`None` for others - e.g.:
+of the media types and will be `None` for others - e.g.:
 
  - `total_episode_count` is only present for seasons
  - `season_number` is present for seasons and episodes
@@ -34,8 +33,8 @@ and to reuse the structure in [`seasons`][simplejustwatchapi.justwatch.seasons].
 Some fields in returned data is marked as optional (through `| None`). Since there is no
 documentation for the JustWatch GraphQL API I tried to mark as optional fields which I
 found to **actually** be optional, rather than mark everything. However, there is no
-guarantee what the API will return, so to be safe you might need to treat **all** fields
-as effectively optional (as in - they can be `None`).
+guarantee what the API will return, so if you need maximum safety you might need to
+treat **all** fields as effectively optional (as in - they can be `None`).
 
 
 
@@ -46,28 +45,33 @@ API does not give specific standards, it will respond with an error with expecte
 regex for invalid ones. You can infer the standard from the regex, however it might not
 be strict.
 
-There is **a** list of supported locales in [JustWatch **REST API** documentation]
-(https://apis.justwatch.com/docs/api/#tips).
-Any combination of those languages and countries should work with this API as well.
+There is **a** list of supported locales in
+[JustWatch **REST API** documentation](https://apis.justwatch.com/docs/api/#tips).
+Any combination of those languages and countries should work with this API as well, but
+it doesn't seem to be comprehensive.
 
 
 ### Country
 
-Two uppercase letters:
+Required pattern is two uppercase letters:
 ```regex
 ^[A-Z]{2}$
 ```
 
-It looks like **ISO 3166-1 alpha-2**.
+It looks like **ISO 3166-1 alpha-2** standard.
 
 API expects only uppercase letters, however this library will automatically convert
 country codes to uppercase.
 
+If country code doesn't match the regex, or isn't a valid code the API will respond
+with an internal error and [`JustWatchApiError`]
+[simplejustwatchapi.exceptions.JustWatchApiError] will be raised.
+
 
 ### Language
 
-Two lowercase letters with optional alphanumeric suffix after `-`. The sufix must be
-uppercase:
+Required pattern is 2 lowercase letters with optional alphanumeric suffix after `-`.
+The sufix must be uppercase:
 ```
 ^[a-z]{2}(-[0-9A-Z]+)?$
 ```
@@ -78,20 +82,33 @@ allows only for numbers and uppercase letters.
 **The provided language isn't modified at all by this library, so it must match the
 regex exactly, including letter case.**
 
+If language code doesn't match the expected regex the API will respond with an internal
+error and [`JustWatchApiError`][simplejustwatchapi.exceptions.JustWatchApiError] will be
+raised.
+
+If the code **does** match the regex, but isn't a valid code, then the API defaults to
+english and no exception is raised.
+
+!!! note "Discrepancy between invalid country and language codes"
+    API handles codes matching expected pattern, but still not valid differently between
+    country and language - for country API will return and error, thus exception will
+    be raised; while for language it will default to english.
 
 
-## Request complexity
 
-JustWatch API will respond with error on too high request/response complexity -
+## Operation complexity
+
+JustWatch API will respond with error on too high operation complexity -
 essentially when returned graph would be too large. It's the reason for why
 seasons/episodes data isn't available directly in
 [`search`][simplejustwatchapi.justwatch.search],
 [`popular`][simplejustwatchapi.justwatch.popular], or
 [`details`][simplejustwatchapi.justwatch.details] functions (mostly the first one).
 
-This issue can still occur for [`search`][simplejustwatchapi.justwatch.search]
-with too high `count` value. In my tests the limit is around 100 (in the worst case with
-`best_only = False`). It's a lot, but keep it in mind.
+This issue can still occur for [`search`][simplejustwatchapi.justwatch.search] and
+[`popular`][simplejustwatchapi.justwatch.popular] with too high `count` value.
+In my tests the limit is around 100 (in the worst case with `best_only = False`).
+It's a lot, but keep it in mind.
 
 Using `best_only=True` should alleviate the issue somewhat, so for very large requests I
 recommend using its default `True` value.
@@ -106,20 +123,21 @@ If you need even more entries you can retrieve data in chunks using `offset` par
 ## Maximum number of entries
 
 The JustWatch API itself won't allow for getting more than 1999 entries, through `count`
-and `offset`, regardless of request complexity. If you try to get the 2000th entry, the
-API (and functions in this libary) will return an empty list.
+and `offset`, regardless of operation complexity. If you try to get the 2000th entry,
+the API (and functions in this libary) will return an empty list.
 
 **If you try to access over the 1999th entry you won't get *up to* 1999 entries,
 you'll get an empty list.**
 
-For example, this will get you entries 1990 - 1999 - a 9 element list of `MediaEntry`,
+For example, this will get you entries 1990 - 1999 - a 9 element list of [`MediaEntry`]
+[simplejustwatchapi.tuples.MediaEntry],
 as expected:
 
 ```python
 from simplejustwatchapi import search
 
 results = search("title", count=9, offset=1990)
-# len(results) == 9, as expected
+# len(results) == 9, as expected.
 ```
 
 But trying to get 1990 - 2000 will result in an empty list:
@@ -128,7 +146,7 @@ But trying to get 1990 - 2000 will result in an empty list:
 from simplejustwatchapi import search
 
 results = search("title", count=10, offset=1990)
-# len(results) == 0, API responded with empty list
+# len(results) == 0, API responded with empty list.
 ```
 
 Overshooting will also result in an empty list:
@@ -137,17 +155,17 @@ Overshooting will also result in an empty list:
 from simplejustwatchapi import search
 
 results = search("title", count=100, offset=1950)
-# len(results) == 0, API responded with empty list
+# len(results) == 0, API responded with empty list.
 ```
 
-Interestingly, you'll still hit [too high request complexity](#request-complexity)
+Interestingly, you'll still hit [too high operation complexity](#operation-complexity)
 for too high values of `count`, even though you'd get an empty list anyway:
 
 ```python
 from simplejustwatchapi import search
 
 results = search("title", count=200, offset=1950)
-# Errors out due to complexity
+# Errors out due to complexity.
 ```
 
 
@@ -161,8 +179,8 @@ results = search("title", count=200, offset=1950)
 
 !!! note "Invalid codes provide no filtering"
     If you try to use invalid/unexpected codes for a given country then **no filtering
-    will be done at all**. There will be nointernal errors, functions will return
-    normal values, rather than some kind of empty response.
+    will be done at all**. There will be no internal errors, or exceptions; functions
+    will return normal values, rather than some kind of empty response.
 
 ### [`providers`][simplejustwatchapi.justwatch.providers] function
 
@@ -210,20 +228,24 @@ So the codes for them are `amp` and `nfx` for the US.
 The codes are also returned when looking up offers (through pretty much any function
 aside from [`providers`][simplejustwatchapi.justwatch.providers]) through
 [`OfferPackage`][simplejustwatchapi.tuples.OfferPackage] and its `short_name` field.
-For example, to get a `dict` "**full name**": "**code**" you can:
+For example, to get the codes from [`search`][simplejustwatchapi.justwatch.search]:
 
 ```python
-from simplejustwatchapi import search
+from simplejustwatchapi import popular, search
 
-results = search("title", "US", "en", 5, True)
+search_results = search("The Matrix", "US", "en", 5, True)
 name_to_code_dict = {
     # Get name and short_name/code from packages:
     offer.package.name: offer.package.short_name
-    for entry in results  # Iterate all entries
-    for offer in entry.offers  # Iterate all offers per entry
+    for entry in search_results  # Iterate all entries.
+    for offer in entry.offers  # Iterate all offers per entry.
 }
+# Keep country code the same between functions, as different countries might have
+# different provider codes.
+# Also, "providers" needs to be a list, not a dict.
+popular_results = popular("US", providers=list(name_to_code_dict.values()))
 ```
 
-!!! tip
+!!! tip "When this actually might be useful"
     This only makes sense if you are already using other functions. To get **just** the
-    codes use the [`providers`](#providers-function) function.
+    codes use the [`providers`](#providers-function) function instead.

docs/index.md

@@ -22,15 +22,12 @@ This library provides multiple functions for accessing JustWatch:
 
  - `search` - search for entries based on title
  - `popular` - get a list of currently popular titles
- - `details` - get details for entry based on its node ID
+ - `details` - get details for a title based on its ID
  - `seasons` - get information about all seasons of a show
  - `episodes` - get information about all episodes of a season
- - `offers_for_countries` - get offers for entry based on its node ID,
-    can look for offers in multiple countries
- - `providers` - get data about available providers (e.g., Netflix)
-
-All functions return response from JustWatch API parsed into a [`NamedTuple`]
-[typing.NamedTuple].
+ - `offers_for_countries` - get offers for a title based on its ID for multiple
+    countries
+ - `providers` - get data about all available providers (like Netflix) in a country
 
 All needed functions, data structures, raised exceptions are available through single
 module `simplejustwatchapi`.

docs/usage.md

@@ -8,20 +8,21 @@ This library provides multiple functions for accessing JustWatch:
 
  - `search` - search for entries based on title
  - `popular` - get a list of currently popular titles
- - `details` - get details for entry based on its node ID
+ - `details` - get details for a title based on its ID
  - `seasons` - get information about all seasons of a show
  - `episodes` - get information about all episodes of a season
- - `offers_for_countries` - get offers for entry based on its node ID,
-    can look for offers in multiple countries
- - `providers` - get data about available providers (e.g., Netflix)
+ - `offers_for_countries` - get offers for a title based on its ID for multiple
+    countries
+ - `providers` - get data about all available providers (like Netflix) in a country
 
 All functions return response from JustWatch API parsed into a [`NamedTuple`]
-[typing.NamedTuple].
+[typing.NamedTuple], check [Data structures](API Reference/data.md) page for more
+details.
 
 All needed functions, data structures, raised exceptions are available through single
-module `simplejustwatchapi`.
+module - `simplejustwatchapi`.
 
-Examples of parsed [`NamedTuple`][typing.NamedTuple] are in the GitHub repository in
+Examples of parsed responses are in the GitHub repository in
 [`examples/`](https://github.com/Electronic-Mango/simple-justwatch-python-api/tree/\
 main/examples).
 
@@ -92,7 +93,7 @@ If JustWatch GraphQL API returns fewer entries, then this function will also ret
 `best_only` determines whether similar offers, but lower quality should be included in response.
 If a platform offers streaming for a given entry in 4K, HD and SD, then `best_only = True` will return only the 4K offer, `best_only = False` will return all three.
 
-`offset` allows for very basic pagination, letting you get more data without running into [request complexity](#request-complexity).
+`offset` allows for very basic pagination, letting you get more data without running into [operation complexity](caveats.md#operation-complexity).
 It simply skips `offset` number of first entries (on the API side, nothing is done inside the library).
 Since there is no session there's no guarantee of results "stability" - if JustWatch decides to
 shuffle returned values (I'm not sure what would be the reason, but in theory it's possible)
@@ -107,7 +108,7 @@ or check [Provider codes](#provider-codes) for more details.
 
 Returned value is a list of [`MediaEntry`](#return-data-structures) objects.
 
-For very large searches (high `count` value) I recommend using default `best_only=True` to avoid issues with [request complexity](#request-complexity).
+For very large searches (high `count` value) I recommend using default `best_only=True` to avoid issues with [operation complexity](caveats.md#operation-complexity).
 
 Example function call and its output is in [`examples/search_output.py`](examples/search_output.py).
 
@@ -146,7 +147,7 @@ If JustWatch GraphQL API returns fewer entries, then this function will also ret
 `best_only` determines whether similar offers, but lower quality should be included in response.
 If a platform offers streaming for a given entry in 4K, HD and SD, then `best_only = True` will return only the 4K offer, `best_only = False` will return all three.
 
-`offset` allows for very basic pagination letting you get more data without running into [request complexity](#request-complexity).
+`offset` allows for very basic pagination letting you get more data without running into [operation complexity](caveats.md#operation-complexity).
 It simply skips first entries (on the API side, nothing is done inside the library).
 Since there is no session there's no guarantee of results "stability" - if JustWatch decides to
 shuffle returned values (I'm not sure what would be the reason, but in theory it's possible)
@@ -161,7 +162,7 @@ or check [Provider codes](#provider-codes) for more details.
 
 Returned value is a list of [`MediaEntry`](#return-data-structures) objects.
 
-For very large searches (high `count` value) I recommend using default `best_only=True` to avoid issues with [request complexity](#request-complexity).
+For very large searches (high `count` value) I recommend using default `best_only=True` to avoid issues with [operation complexity](caveats.md#operation-complexity).
 
 Example function call and its output is in [`examples/popular_output.py`](examples/popular_output.py).
 
@@ -323,11 +324,98 @@ Example function call and its output is in [`examples/providers_output.py`](exam
 
 Each function can raise two exceptions:
 
-| Exception | Cause |
-|-----------|-------|
+| Exception                                                                | Cause |
+|--------------------------------------------------------------------------|-------|
 | [`JustWatchHttpError`][simplejustwatchapi.exceptions.JustWatchHttpError] | JustWatch API responded with non-`2xx` code. |
-| [`JustWatchApiError`][simplejustwatchapi.exceptions.JustWatchApiError] | JSON response from JustWatch API contains errors. If this exception is raised, then API responded with `2xx` code. |
+| [`JustWatchApiError`][simplejustwatchapi.exceptions.JustWatchApiError]   | JSON response from JustWatch API contains errors,<br>even though the API responded with a `2xx` status code. |
 
+You can check [Exceptions](API Reference/exceptions.md) page for more details.
+
+### HTTP errors
+
+Non-`2xx` response status codes can happen when trying to use incorrect type for
+parameters, e.g., trying to use a non-numeric string for `count`:
+
+```python
+from simplejustwatchapi import search, JustWatchHttpError
+
+try:
+    results = search("The Matrix", count="five")
+except JustWatchHttpError as e:
+    print(e.code, e.message)
+    # In this case "e.message" is a JSON, but handled as a regular string.
+```
+
+!!! note "Numeric strings instead of `int`"
+    Since requests are send as a JSON you can use strings for `int` arguments, as long
+    as they are numeric strings, like `5`, instead of `five`:
+
+    ```python
+    from simplejustwatchapi import search
+
+    results = search("The Matrix", count="5")
+    # No exception is raised.
+    ```
+
+
+### API errors
+
+API errors can occur for invalid country code:
+```python
+from simplejustwatchapi import search, JustWatchApiError
+
+try:
+    # Country code matches 2-letter pattern, but isn't a valid code for any country.
+    results = search("The Matrix", country="xx")
+except JustWatchApiError as e:
+    # Print all error messages.
+    error_messages = [error.get("message") for error in e.errors]
+    print(",".join(error_messages))
+```
+
+It can occur for language codes not matching expected pattern:
+```python
+from simplejustwatchapi import search, JustWatchApiError
+
+try:
+    # Language code "xx" also isn't valid for any languages, but since it matches the
+    # pattern it would default to english.
+    results = search("The Matrix", language="xxx")
+except JustWatchApiError as e:
+    # Print only error codes.
+    # Codes are collected to a set, as the API will return an error for each place,
+    # where language code is used, in all offers, descriptions, etc.
+    error_codes = {error["extensions"]["code"] for error in e.errors}
+    print(",".join(error_codes))
+```
+
+Using title, instead of ID in [`details`][simplejustwatchapi.justwatch.details]
+function:
+
+```python
+from simplejustwatchapi import details, JustWatchError
+
+try:
+    # "details" expects an ID, not a title.
+    results = details("The Matrix")
+except JustWatchError as e:
+    # JustWatchError will catch both API and HTTP exceptions.
+    print(e.errors)
+```
+
+Too high operation complexity due to too large `count`:
+
+```python
+from simplejustwatchapi import search, JustWatchApiError
+
+try:
+    results = search("The Matrix", count=500)
+except JustWatchApiError as e:
+    error_messages = [error.get("message") for error in e.errors]
+    print(",".join(error_messages))
+```
+
+And, probably, many other, similar, cases as well.
 
 
 ## Advanced examples