python-amazon-paapi 7.0.0__py3-none-any.whl → 7.1.0__py3-none-any.whl

amazon_creatorsapi/aio/api.py

@@ -87,6 +87,7 @@ from creatorsapi_python_sdk.models.search_items_resource import SearchItemsResou
 if TYPE_CHECKING:
     from types import TracebackType
 
+    from amazon_creatorsapi.core.constants import TimeoutValue
     from amazon_creatorsapi.core.marketplaces import CountryCode
     from creatorsapi_python_sdk.models.availability import Availability
     from creatorsapi_python_sdk.models.condition import Condition
@@ -168,8 +169,9 @@ class AsyncAmazonCreatorsApi:
         country: Country code (e.g., "ES", "US"). Used to determine marketplace.
         marketplace: Marketplace URL (e.g., "www.amazon.es"). Overrides country.
         throttling: Wait time in seconds between API calls. Defaults to 1 second.
-        timeout: Request timeout in seconds, or None to wait indefinitely.
-            Defaults to 30 seconds.
+        timeout: Request timeout in seconds, a pair of ``(connect, read)``
+            seconds bounding each leg on its own, or None to wait
+            indefinitely. Defaults to 5 seconds to connect and 25 to read.
         retries: Extra attempts for the failures that Amazon asks to retry,
             waiting longer before every attempt. Defaults to 3.
         host: Base URL of the API. Defaults to the Amazon Creators API.
@@ -196,7 +198,7 @@ class AsyncAmazonCreatorsApi:
         country: CountryCode | None = None,
         marketplace: str | None = None,
         throttling: float = DEFAULT_THROTTLING,
-        timeout: float | None = DEFAULT_TIMEOUT,
+        timeout: TimeoutValue | None = DEFAULT_TIMEOUT,
         retries: int = DEFAULT_RETRIES,
         host: str = DEFAULT_HOST,
         auth_endpoint: str | None = None,

amazon_creatorsapi/aio/auth.py

@@ -7,8 +7,9 @@ from __future__ import annotations
 
 import asyncio
 import time
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
+from amazon_creatorsapi.aio.timeouts import build_httpx_timeout
 from amazon_creatorsapi.core.constants import DEFAULT_TIMEOUT, HTTP_OK
 from amazon_creatorsapi.core.oauth import (
     COGNITO_SCOPE,
@@ -23,6 +24,9 @@ from amazon_creatorsapi.core.oauth import (
 )
 from amazon_creatorsapi.errors import AuthenticationError
 
+if TYPE_CHECKING:
+    from amazon_creatorsapi.core.constants import TimeoutValue
+
 try:
     import httpx
 except ImportError as exc:  # pragma: no cover
@@ -61,8 +65,10 @@ class AsyncOAuth2TokenManager:
         credential_secret: OAuth2 credential secret.
         version: API version (determines auth endpoint).
         auth_endpoint: Optional custom auth endpoint URL.
-        timeout: Token request timeout in seconds, or None to wait
-            indefinitely. Defaults to 30 seconds.
+        timeout: Token request timeout in seconds, a pair of
+            ``(connect, read)`` seconds bounding each leg on its own, or None
+            to wait indefinitely. Defaults to 5 seconds to connect and
+            25 to read.
 
     """
 
@@ -72,7 +78,7 @@ class AsyncOAuth2TokenManager:
         credential_secret: str,
         version: str,
         auth_endpoint: str | None = None,
-        timeout: float | None = DEFAULT_TIMEOUT,
+        timeout: TimeoutValue | None = DEFAULT_TIMEOUT,
     ) -> None:
         """Initialize the async OAuth2 token manager."""
         self._credential_id = credential_id
@@ -189,7 +195,9 @@ class AsyncOAuth2TokenManager:
         }
 
         try:
-            async with httpx.AsyncClient(timeout=self._timeout) as client:
+            async with httpx.AsyncClient(
+                timeout=build_httpx_timeout(self._timeout),
+            ) as client:
                 if self.is_lwa():
                     response = await client.post(
                         self._auth_endpoint,

amazon_creatorsapi/aio/client.py

@@ -12,11 +12,14 @@ from typing import TYPE_CHECKING, Any
 
 from typing_extensions import Self
 
+from amazon_creatorsapi.aio.timeouts import build_httpx_timeout
 from amazon_creatorsapi.core.constants import DEFAULT_TIMEOUT
 
 if TYPE_CHECKING:
     from types import TracebackType
 
+    from amazon_creatorsapi.core.constants import TimeoutValue
+
 try:
     import httpx
 except ImportError as exc:  # pragma: no cover
@@ -65,15 +68,16 @@ class AsyncHttpClient:
 
     Args:
         host: Base URL for API requests. Defaults to Amazon Creators API.
-        timeout: Request timeout in seconds, or None to wait indefinitely.
-            Defaults to 30.
+        timeout: Request timeout in seconds, a pair of ``(connect, read)``
+            seconds bounding each leg on its own, or None to wait
+            indefinitely. Defaults to 5 seconds to connect and 25 to read.
 
     """
 
     def __init__(
         self,
         host: str = DEFAULT_HOST,
-        timeout: float | None = DEFAULT_TIMEOUT,
+        timeout: TimeoutValue | None = DEFAULT_TIMEOUT,
     ) -> None:
         """Initialize the async HTTP client."""
         self._host = host
@@ -85,7 +89,7 @@ class AsyncHttpClient:
         """Enter async context manager, creating a persistent client."""
         self._client = httpx.AsyncClient(
             base_url=self._host,
-            timeout=self._timeout,
+            timeout=build_httpx_timeout(self._timeout),
             headers={"User-Agent": USER_AGENT},
         )
         self._owns_client = True
@@ -134,7 +138,7 @@ class AsyncHttpClient:
             # Create a new client for this request (standalone mode)
             async with httpx.AsyncClient(
                 base_url=self._host,
-                timeout=self._timeout,
+                timeout=build_httpx_timeout(self._timeout),
             ) as client:
                 response = await client.post(
                     path,

amazon_creatorsapi/aio/timeouts.py

@@ -0,0 +1,49 @@
+"""Conversion of the timeout values into the ones httpx understands.
+
+It lives here rather than next to the values themselves because httpx is an
+optional dependency, and the synchronous client must keep importing without
+it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from amazon_creatorsapi.core.constants import TimeoutValue
+
+try:
+    import httpx
+except ImportError as exc:  # pragma: no cover
+    msg = (
+        "httpx is required for async support. "
+        "Install it with: pip install python-amazon-paapi[async]"
+    )
+    raise ImportError(msg) from exc
+
+
+def build_httpx_timeout(
+    timeout: TimeoutValue | None,
+) -> float | httpx.Timeout | None:
+    """Return the timeout to hand to httpx for a value the clients accept.
+
+    A pair is the only value httpx needs help with. Everything else is passed
+    through as it is, so httpx keeps reading it exactly as it did before pairs
+    were accepted.
+
+    Args:
+        timeout: Seconds for the whole request, ``(connect, read)`` seconds
+            per leg, or None to wait indefinitely.
+
+    Returns:
+        The seconds, the httpx timeout built from the pair, or None to wait
+        indefinitely.
+
+    """
+    if not isinstance(timeout, tuple):
+        return timeout
+    connect, read = timeout
+    # httpx reads a pair as (connect, read, write, pool) and leaves the two it
+    # does not find unbounded, which would drop a timeout that the single
+    # value form applies. The read value covers them instead.
+    return httpx.Timeout(connect=connect, read=read, write=read, pool=read)

amazon_creatorsapi/api.py

@@ -77,6 +77,7 @@ from creatorsapi_python_sdk.models.search_items_resource import SearchItemsResou
 if TYPE_CHECKING:
     from types import TracebackType
 
+    from amazon_creatorsapi.core.constants import TimeoutValue
     from amazon_creatorsapi.core.marketplaces import CountryCode
     from creatorsapi_python_sdk.models.availability import Availability
     from creatorsapi_python_sdk.models.browse_node import BrowseNode
@@ -109,8 +110,9 @@ class AmazonCreatorsApi:
         country: Country code (e.g., "ES", "US"). Used to determine marketplace.
         marketplace: Marketplace URL (e.g., "www.amazon.es"). Overrides country.
         throttling: Wait time in seconds between API calls. Defaults to 1 second.
-        timeout: Request timeout in seconds, or None to wait indefinitely.
-            Defaults to 30 seconds.
+        timeout: Request timeout in seconds, a pair of ``(connect, read)``
+            seconds bounding each leg on its own, or None to wait
+            indefinitely. Defaults to 5 seconds to connect and 25 to read.
         retries: Extra attempts for the failures that Amazon asks to retry,
             waiting longer before every attempt. Defaults to 3.
         host: Base URL of the API. Defaults to the Amazon Creators API.
@@ -151,7 +153,7 @@ class AmazonCreatorsApi:
         country: CountryCode | None = None,
         marketplace: str | None = None,
         throttling: float = DEFAULT_THROTTLING,
-        timeout: float | None = DEFAULT_TIMEOUT,
+        timeout: TimeoutValue | None = DEFAULT_TIMEOUT,
         retries: int = DEFAULT_RETRIES,
         host: str = DEFAULT_HOST,
         auth_endpoint: str | None = None,

amazon_creatorsapi/core/auth.py

@@ -14,6 +14,7 @@ from amazon_creatorsapi.errors import AuthenticationError
 from creatorsapi_python_sdk.auth.oauth2_token_manager import OAuth2TokenManager
 
 if TYPE_CHECKING:
+    from amazon_creatorsapi.core.constants import TimeoutValue
     from creatorsapi_python_sdk.auth.oauth2_config import OAuth2Config
 
 
@@ -28,12 +29,17 @@ class TimeoutOAuth2TokenManager(OAuth2TokenManager):
 
     Args:
         config: OAuth2 configuration with the credentials and the endpoint.
-        timeout: Token request timeout in seconds, or None to wait
-            indefinitely.
+        timeout: Token request timeout in seconds, a pair of
+            ``(connect, read)`` seconds bounding each leg on its own, or None
+            to wait indefinitely.
 
     """
 
-    def __init__(self, config: OAuth2Config, timeout: float | None) -> None:
+    def __init__(
+        self,
+        config: OAuth2Config,
+        timeout: TimeoutValue | None,
+    ) -> None:
         """Initialize the token manager with its timeout."""
         super().__init__(config)
         self._timeout = timeout

amazon_creatorsapi/core/constants.py

@@ -1,8 +1,27 @@
 """Constants for the Amazon Creators API."""
 
+from __future__ import annotations
+
+from typing import Union
+
+TimeoutValue = Union[float, "tuple[float, float]"]
+"""Seconds for the whole request, or ``(connect, read)`` seconds per leg.
+
+The pair matters for a host that resolves to several addresses: the connect
+leg is spent once per address, so a single value generous enough to read a
+slow response is also spent on every address that fails to answer.
+"""
+
 DEFAULT_HOST = "https://creatorsapi.amazon"
 DEFAULT_THROTTLING = 1
-DEFAULT_TIMEOUT = 30.0
+# Connect and read seconds, rather than one value covering both. The connect
+# leg is spent once per address the host resolves to, so a single value
+# generous enough to read a slow response is also spent on every address that
+# fails to answer: at 30 seconds, a host resolving to four addresses takes two
+# minutes to give up. The two add up to the 30 seconds this has always
+# documented, and a connection that takes longer than five seconds to
+# establish is not one that a longer wait rescues.
+DEFAULT_TIMEOUT = (5.0, 25.0)
 
 # Maximum amount of item identifiers accepted in a single request
 MAX_ITEMS_PER_REQUEST = 10

amazon_creatorsapi/core/validation.py

@@ -10,6 +10,7 @@ from amazon_creatorsapi.core.marketplaces import MARKETPLACES
 from amazon_creatorsapi.errors import InvalidArgumentError
 
 if TYPE_CHECKING:
+    from amazon_creatorsapi.core.constants import TimeoutValue
     from amazon_creatorsapi.core.marketplaces import CountryCode
 
 RequestT = TypeVar("RequestT", bound=BaseModel)
@@ -44,21 +45,47 @@ def validate_and_get_marketplace(
     raise InvalidArgumentError(msg)
 
 
-def validate_timeout(timeout: float | None) -> float | None:
+def validate_timeout(timeout: TimeoutValue | None) -> TimeoutValue | None:
     """Validate the request timeout value.
 
     Args:
-        timeout: Request timeout in seconds, or None to wait indefinitely.
+        timeout: Request timeout in seconds, a pair of ``(connect, read)``
+            seconds bounding each leg on its own, or None to wait
+            indefinitely.
 
     Returns:
-        The timeout as a float, or None when disabled.
+        The timeout as a float, as a pair of floats, or None when disabled.
 
     Raises:
-        InvalidArgumentError: If the timeout is not greater than zero.
+        InvalidArgumentError: If a timeout is not greater than zero, or if a
+            pair does not hold exactly two of them.
 
     """
     if timeout is None:
         return None
+    if not isinstance(timeout, tuple):
+        return _validate_seconds(timeout)
+    try:
+        connect, read = timeout
+    except ValueError as error:
+        msg = f"Timeout must be a pair of (connect, read) seconds: {timeout!r}"
+        raise InvalidArgumentError(msg) from error
+    return _validate_seconds(connect), _validate_seconds(read)
+
+
+def _validate_seconds(timeout: float) -> float:
+    """Validate a number of seconds used as a timeout.
+
+    Args:
+        timeout: Timeout in seconds, whether on its own or one leg of a pair.
+
+    Returns:
+        The timeout as a float.
+
+    Raises:
+        InvalidArgumentError: If it is not a number greater than zero.
+
+    """
     try:
         value = float(timeout)
     except (TypeError, ValueError) as error:

{python_amazon_paapi-7.0.0.dist-info → python_amazon_paapi-7.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-amazon-paapi
-Version: 7.0.0
+Version: 7.1.0
 Summary: Amazon Creators API wrapper for Python
 Project-URL: Homepage, https://github.com/sergioteula/python-amazon-paapi
 Project-URL: Repository, https://github.com/sergioteula/python-amazon-paapi
@@ -260,8 +260,11 @@ The interval is kept per client and is safe to share between threads.
 
 ### Timeout
 
-Timeout value represents the number of seconds to wait for a response before failing,
-being the default value 30 seconds. Use `None` to wait indefinitely.
+Timeout value represents the number of seconds to wait for a response before failing.
+Use `None` to wait indefinitely.
+
+The default is `(5, 25)`: five seconds to establish the connection and twenty-five to
+read the response, thirty in total.
 
 ```python
 api = AmazonCreatorsApi(ID, SECRET, VERSION, TAG, COUNTRY, timeout=10)  # Fails after 10 seconds
@@ -270,6 +273,16 @@ api = AmazonCreatorsApi(ID, SECRET, VERSION, TAG, COUNTRY, timeout=0.5)  # Fails
 
 It applies to every API request, including the OAuth2 token refresh.
 
+A pair of `(connect, read)` seconds bounds each leg of the request on its own. This
+matters for a host resolving to several addresses: the connect leg is spent once per
+address, so a single value generous enough to read a slow response is also spent on
+every address that fails to answer.
+
+```python
+# Gives up on an unresponsive address after 1 second, and still reads for 10
+api = AmazonCreatorsApi(ID, SECRET, VERSION, TAG, COUNTRY, timeout=(1, 10))
+```
+
 ### Retries
 
 Amazon asks clients to back off and try again when it throttles a request or fails to

{python_amazon_paapi-7.0.0.dist-info → python_amazon_paapi-7.1.0.dist-info}/RECORD

@@ -1,15 +1,16 @@
 amazon_creatorsapi/__init__.py,sha256=Ioi8TxeQHQHrlNsFhYW0nRZIeodXg2N5xZXQEXKz4jc,298
-amazon_creatorsapi/api.py,sha256=32PYOqw5ZjET2J0c14su6WF8gHE1wLw11TnkOKSgBUo,26229
+amazon_creatorsapi/api.py,sha256=ZSfDT7MNYvFpL4bg-hlNyZqEXvVdjidHKSo7zbGzhp4,26404
 amazon_creatorsapi/errors.py,sha256=C7ddKHbMGjdaXEVAg1iDjPEyolpzxGx30tafgk8OcGo,1613
 amazon_creatorsapi/models.py,sha256=u9MYkNUHyWt0J_eHb0HO4rPb8Gqbjczyqv33NXJ79_c,5975
 amazon_creatorsapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 amazon_creatorsapi/aio/__init__.py,sha256=Z76dMFKs0vPZakdXxoGq2dsWmkx-tUkx88NmHBq1DHU,398
-amazon_creatorsapi/aio/api.py,sha256=8znD6MNMTdcPJRh_MMvVm4L6olhN8SntOiJ0ENDhPKA,30777
-amazon_creatorsapi/aio/auth.py,sha256=skYcIqKR-nSAcbZzMm80slepsxjTQepj6skt1cV7v1k,8279
-amazon_creatorsapi/aio/client.py,sha256=ULBQwnPKszEbj6quhbyBxlslb-FDoBKQGnreRH886gU,4490
+amazon_creatorsapi/aio/api.py,sha256=1idnlUz1EiHYgfLvuwehIWgKb2CP-kOV6RiKXF5J5Hc,30952
+amazon_creatorsapi/aio/auth.py,sha256=Unkr9LgaE30o9inTkl1271sI34cFVD1b6E2wG14ncSI,8616
+amazon_creatorsapi/aio/client.py,sha256=ASPjzFG_e2L1La0U3RekiCdZpYgphtuFqssReTH-CFU,4780
+amazon_creatorsapi/aio/timeouts.py,sha256=uHRfF7aBHNyqqGqzrEPXXG5K-VmIVbc7K6QGYFYbN8E,1608
 amazon_creatorsapi/core/__init__.py,sha256=3wb1H-IKqVShgbqfAlF8j5Nl9bIx_UMP2BDvRBvtnEk,146
-amazon_creatorsapi/core/auth.py,sha256=qWEowrmLScgZAq15UmUvFM09z_LMwpsWNFZju_pvVDw,4918
-amazon_creatorsapi/core/constants.py,sha256=N9nub-SCUZ2WxFKms5pnVEg-AIAdBjiwDhiRvYK9tYQ,383
+amazon_creatorsapi/core/auth.py,sha256=kTzOmrZWhC7ugW-g3DBM_By7vi5qH4AcmgEsYRAkskA,5099
+amazon_creatorsapi/core/constants.py,sha256=jRWAMxYuMbHpFGdjJAq_F6i-7GzpweUxnd88LyiyFeY,1299
 amazon_creatorsapi/core/error_handling.py,sha256=yUBN1S7OAWIO2EYeKdtCiqTpmMkMoBCQobP_T_2nH6E,5830
 amazon_creatorsapi/core/items.py,sha256=iI2wkKr0k73k1tSRz2jSK20bG1h5Or_aesP8rHd0qKY,1968
 amazon_creatorsapi/core/marketplaces.py,sha256=GpoG82iEviC3Po_Hrdywo4Tl_p5F7iktB_CXW9lMDbM,1753
@@ -19,7 +20,7 @@ amazon_creatorsapi/core/requests.py,sha256=0vBRB0Zl3PdctTqQRW2YaOHjciO9Z9Rsdkmbg
 amazon_creatorsapi/core/resources.py,sha256=JoUKfENnyhrksgRYkB-IEdDGLlBf3W_3G04eO0FULJw,558
 amazon_creatorsapi/core/results.py,sha256=HXTJOoP4S2_hzEgTewgKSGk4Hpnc7QNmj73EG37PrAE,1134
 amazon_creatorsapi/core/retry.py,sha256=LGlhd8qCl15HZMJIOnMwps3jg4lZdYtP1foNtcCffFY,2916
-amazon_creatorsapi/core/validation.py,sha256=KQUWolwUD70CeqxoK-b_BHZyiZt_8YrRW4yKCXNSvAE,4700
+amazon_creatorsapi/core/validation.py,sha256=F4_5woqt5qXWCQIoWZFm2yDzFy4BOjI1l1xnzThkWuY,5629
 creatorsapi_python_sdk/__init__.py,sha256=TGp-BhzlfTVRrvEPUiJ7lmwNwebnRICdxeYcpIFlvSQ,8722
 creatorsapi_python_sdk/api_client.py,sha256=lSQo2r83MXFvPuTD1Zt46MfD7AeE5es5olCIxPS1tzo,32221
 creatorsapi_python_sdk/api_response.py,sha256=eMxw1mpmJcoGZ3gs9z6jM4oYoZ10Gjk333s9sKxGv7s,652
@@ -125,7 +126,7 @@ creatorsapi_python_sdk/models/variation_summary.py,sha256=98Zl9PmBF1lvd1xqKS3XZl
 creatorsapi_python_sdk/models/variation_summary_price.py,sha256=KbXfL21Smb1y9q0yu33t-5IW4FV20roFpiADzsNmx1Y,3533
 creatorsapi_python_sdk/models/variations_result.py,sha256=055KMPzIva1JX2AEV2v-i_yQ0AmkGTB3yFi3vCPqoHU,4113
 creatorsapi_python_sdk/models/website_sales_rank.py,sha256=nSkIVj6quN7ZYu1_A-kMrwmPikvWAZRr5JRmd1ysGnM,3346
-python_amazon_paapi-7.0.0.dist-info/METADATA,sha256=pLnQ_Pht_S8rVS13l-OT_tyhurVIDd79AVPWI2N7xZ0,15426
-python_amazon_paapi-7.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-python_amazon_paapi-7.0.0.dist-info/licenses/LICENSE,sha256=pA7Z3pwvEEHJgQ2d9o8RTVUMxc_GMJNosLRWVwue7PQ,1068
-python_amazon_paapi-7.0.0.dist-info/RECORD,,
+python_amazon_paapi-7.1.0.dist-info/METADATA,sha256=EacVxEthhomPBetvMmKBfae_LMTOH-yGhBGMud1BA10,15971
+python_amazon_paapi-7.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+python_amazon_paapi-7.1.0.dist-info/licenses/LICENSE,sha256=pA7Z3pwvEEHJgQ2d9o8RTVUMxc_GMJNosLRWVwue7PQ,1068
+python_amazon_paapi-7.1.0.dist-info/RECORD,,