fix: keep the code of version 6 working and document what still breaks

CHANGELOG.md

@@ -9,11 +9,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Migration guide from version 6, listing what can break in code written for `amazon_creatorsapi` and how to fix it
 - The values accepted by `version`, the countries and the marketplace each one maps to, and the `marketplace` argument are documented, instead of having to read the code to find them
 - `CONTRIBUTING.md`, with the setup of the project, the commands of the `Makefile`, the conventions of the code and the tests, and what a pull request is expected to carry
+- Tests pinning the signatures of both clients and the hierarchy of the errors, so a change that breaks the code of the users is noticed
 
 ### Changed
 
+- `availability` is a keyword only argument of `search_items`, placed after the rest, instead of sitting between `item_page` and `condition`, where it displaced every following argument of a caller not using keywords
+- `AuthenticationError` and `AccessDeniedError` are subclasses of `RequestError`, which is what a failed request raised before they got their own type
+- `InvalidArgumentError` is also a `ValueError`, as the `pydantic.ValidationError` and the plain `ValueError` it replaced were
+- An unsupported `version` raises `InvalidArgumentError` instead of a plain `ValueError`, like the rest of the arguments of the clients
 - A `version` of a family that the library cannot authenticate is rejected even when `auth_endpoint` is given, instead of being sent with the Cognito flow and rejected by Amazon without an explanation
 - The error of an unsupported version tells that a newer version of a known family can be used by providing its `auth_endpoint`
 - The auth flow of a version and the `Authorization` header it expects are decided in a single place, and the copies bundled in the SDK are pinned to them by tests, so a bump of the SDK cannot leave both halves disagreeing

README.md

@@ -391,6 +391,7 @@ back as `None`.
 
 - 📖 [Full documentation](https://python-amazon-paapi.readthedocs.io/)
 - 📘 [Usage guide](https://python-amazon-paapi.readthedocs.io/en/latest/pages/usage-guide.html)
+- 🔀 [Migration guide from version 6](https://python-amazon-paapi.readthedocs.io/en/latest/pages/migration-guide-7.html)
 - 🔀 [Migration guide from `amazon_paapi`](https://python-amazon-paapi.readthedocs.io/en/latest/pages/migration-guide-6.html)
 - 📋 [Changelog](https://github.com/sergioteula/python-amazon-paapi/blob/master/CHANGELOG.md)
 - 💬 [Telegram support group](https://t.me/PythonAmazonPAAPI)

amazon_creatorsapi/aio/api.py

@@ -178,13 +178,12 @@ class AsyncAmazonCreatorsApi:
 
     Raises:
         InvalidArgumentError: If neither country nor marketplace is provided,
-            if timeout is not greater than zero, if throttling is negative or
-            if retries is negative.
-        ValueError: If the version is not one of the supported ones, which
-            the message of the error lists, and no auth_endpoint is given, or
-            if it belongs to a family that the library cannot authenticate
-            (2.x and 3.x are the supported ones), which no auth_endpoint
-            makes valid.
+            if timeout is not greater than zero, if throttling is negative,
+            if retries is negative, if the version is not one of the supported
+            ones, which the message of the error lists, and no auth_endpoint
+            is given, or if it belongs to a family that the library cannot
+            authenticate (2.x and 3.x are the supported ones), which no
+            auth_endpoint makes valid.
 
     """
 
@@ -346,7 +345,6 @@ async def search_items(
         search_index: str | None = None,
         item_count: int | None = None,
         item_page: int | None = None,
-        availability: Availability | None = None,
         condition: Condition | None = None,
         currency_of_preference: str | None = None,
         delivery_flags: list[DeliveryFlag] | None = None,
@@ -357,6 +355,8 @@ async def search_items(
         min_reviews_rating: int | None = None,
         sort_by: SortBy | None = None,
         resources: list[SearchItemsResource] | None = None,
+        *,
+        availability: Availability | None = None,
     ) -> SearchResult:
         """Search for items on Amazon based on a search query.
 
@@ -374,8 +374,6 @@ async def search_items(
             search_index: Product category to search. Defaults to All.
             item_count: Number of items returned (1-100). Defaults to 10.
             item_page: Page of items to return (1-10). Defaults to 1.
-            availability: Filter results by availability. Defaults to
-                returning only the items available for purchase.
             condition: Filter offers by condition type.
             currency_of_preference: ISO 4217 currency code for prices.
             delivery_flags: Delivery programs to filter search results by.
@@ -386,6 +384,9 @@ async def search_items(
             min_reviews_rating: Min review rating (1-4).
             sort_by: Sort method for results.
             resources: List of resources to retrieve. Defaults to all.
+            availability: Filter results by availability. Defaults to
+                returning only the items available for purchase. Keyword only,
+                so it does not shift the position of the other arguments.
 
         Returns:
             SearchResult containing the list of items.

amazon_creatorsapi/aio/auth.py

@@ -100,7 +100,8 @@ def _determine_auth_endpoint(
             The OAuth2 token endpoint URL.
 
         Raises:
-            ValueError: If version is not supported and no custom endpoint provided.
+            InvalidArgumentError: If version is not supported and no custom
+                endpoint provided.
 
         """
         return get_auth_endpoint(version, auth_endpoint)

amazon_creatorsapi/api.py

@@ -119,13 +119,12 @@ class AmazonCreatorsApi:
 
     Raises:
         InvalidArgumentError: If neither country nor marketplace is provided,
-            if timeout is not greater than zero, if throttling is negative or
-            if retries is negative.
-        ValueError: If the version is not one of the supported ones, which
-            the message of the error lists, and no auth_endpoint is given, or
-            if it belongs to a family that the library cannot authenticate
-            (2.x and 3.x are the supported ones), which no auth_endpoint
-            makes valid.
+            if timeout is not greater than zero, if throttling is negative,
+            if retries is negative, if the version is not one of the supported
+            ones, which the message of the error lists, and no auth_endpoint
+            is given, or if it belongs to a family that the library cannot
+            authenticate (2.x and 3.x are the supported ones), which no
+            auth_endpoint makes valid.
 
     Example:
         >>> api = AmazonCreatorsApi(
@@ -310,7 +309,6 @@ def search_items(
         search_index: str | None = None,
         item_count: int | None = None,
         item_page: int | None = None,
-        availability: Availability | None = None,
         condition: Condition | None = None,
         currency_of_preference: str | None = None,
         delivery_flags: list[DeliveryFlag] | None = None,
@@ -321,6 +319,8 @@ def search_items(
         min_reviews_rating: int | None = None,
         sort_by: SortBy | None = None,
         resources: list[SearchItemsResource] | None = None,
+        *,
+        availability: Availability | None = None,
     ) -> SearchResult:
         """Search for items on Amazon based on a search query.
 
@@ -338,8 +338,6 @@ def search_items(
             search_index: Product category to search. Defaults to All.
             item_count: Number of items returned (1-100). Defaults to 10.
             item_page: Page of items to return (1-10). Defaults to 1.
-            availability: Filter results by availability. Defaults to
-                returning only the items available for purchase.
             condition: Filter offers by condition type.
             currency_of_preference: ISO 4217 currency code for prices.
             delivery_flags: Delivery programs to filter search results by.
@@ -350,6 +348,9 @@ def search_items(
             min_reviews_rating: Min review rating (1-4).
             sort_by: Sort method for results.
             resources: List of resources to retrieve. Defaults to all.
+            availability: Filter results by availability. Defaults to
+                returning only the items available for purchase. Keyword only,
+                so it does not shift the position of the other arguments.
 
         Returns:
             SearchResult containing the list of items.

amazon_creatorsapi/core/oauth.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from amazon_creatorsapi.errors import InvalidArgumentError
+
 # Scopes and grant type accepted by the auth endpoints of Amazon
 COGNITO_SCOPE = "creatorsapi/default"
 LWA_SCOPE = "creatorsapi::default"
@@ -107,8 +109,8 @@ def get_auth_endpoint(version: str, auth_endpoint: str | None = None) -> str:
         The URL used to get the OAuth2 token.
 
     Raises:
-        ValueError: If the family of the version is unknown, or if the version
-            is not in the list and no endpoint is given.
+        InvalidArgumentError: If the family of the version is unknown, or if
+            the version is not in the list and no endpoint is given.
 
     """
     endpoint = auth_endpoint.strip() if auth_endpoint else ""
@@ -126,7 +128,7 @@ def get_auth_endpoint(version: str, auth_endpoint: str | None = None) -> str:
             f"authenticate the {families} versions, so a newer one needs "
             f"support added to the library and not just a custom auth_endpoint"
         )
-        raise ValueError(msg)
+        raise InvalidArgumentError(msg)
 
     if not endpoint:
         supported = ", ".join(VERSION_ENDPOINTS)
@@ -135,6 +137,6 @@ def get_auth_endpoint(version: str, auth_endpoint: str | None = None) -> str:
             f"{supported}. A newer version of a known family can be used by "
             f"providing its auth_endpoint"
         )
-        raise ValueError(msg)
+        raise InvalidArgumentError(msg)
 
     return endpoint

amazon_creatorsapi/errors.py

@@ -5,8 +5,12 @@ class AmazonCreatorsApiError(Exception):
     """Base exception for Amazon Creators API."""
 
 
-class InvalidArgumentError(AmazonCreatorsApiError):
-    """Raised when an invalid argument is provided."""
+class InvalidArgumentError(AmazonCreatorsApiError, ValueError):
+    """Raised when an invalid argument is provided.
+
+    Also a ValueError, so the code written against the errors that pydantic
+    and the version check raised before keeps catching it.
+    """
 
 
 class RequestError(AmazonCreatorsApiError):
@@ -25,12 +29,20 @@ class AssociateValidationError(AmazonCreatorsApiError):
     """Raised when associate credentials are invalid."""
 
 
-class AuthenticationError(AmazonCreatorsApiError):
-    """Raised when OAuth2 authentication fails."""
+class AuthenticationError(RequestError):
+    """Raised when OAuth2 authentication fails.
+
+    A request that fails to authenticate is a failed request, so it is also a
+    RequestError.
+    """
+
 
+class AccessDeniedError(RequestError):
+    """Raised when the credentials cannot perform the requested operation.
 
-class AccessDeniedError(AmazonCreatorsApiError):
-    """Raised when the credentials cannot perform the requested operation."""
+    A request rejected for lack of access is a failed request, so it is also
+    a RequestError.
+    """
 
 
 class ResourceNotFoundError(AmazonCreatorsApiError):

docs/index.rst

@@ -56,15 +56,17 @@ API Reference
 
    amazon_creatorsapi.models
 
-Migration guide
----------------
+Migration guides
+----------------
 
-If you are still using the removed ``amazon_paapi`` module, follow this guide to move to
-``amazon_creatorsapi``.
+Follow the version 7 guide to upgrade code written for ``amazon_creatorsapi`` on version
+6. If you are still using the removed ``amazon_paapi`` module, start with the Creators
+API guide instead.
 
 .. toctree::
    :maxdepth: 1
 
+   ./pages/migration-guide-7.md
    ./pages/migration-guide-6.md
 
 Changelog