python-mope 0.3.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

mope/__version__.py

@@ -1,2 +1,2 @@
 __author__ = "lemuel@vokality.com"
-__version__ = "0.3.0"
+__version__ = "0.3.1"

mope/client.py

@@ -1,4 +1,5 @@
 from collections.abc import Iterable, Mapping, Set
+from math import isfinite
 from typing import IO, Protocol, TypeAlias
 from urllib.parse import urljoin
 
@@ -29,19 +30,45 @@ RequestData: TypeAlias = (
     | str
     | bytes
 )
+RequestTimeout: TypeAlias = float | tuple[float, float]
 
 _user_agent = f"Python Mope {__version__}"
+_BASE_URL = "https://api.mope.sr/api/"
+_DEFAULT_TIMEOUT = (5.0, 30.0)
+
+
+def _timeout_seconds(value: object) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise TypeError("timeout must contain numbers of seconds")
+    try:
+        seconds = float(value)
+    except OverflowError as error:
+        raise ValueError("timeout must be finite and greater than zero") from error
+    if not isfinite(seconds) or seconds <= 0:
+        raise ValueError("timeout must be finite and greater than zero")
+    return seconds
+
+
+def _request_timeout(value: object) -> RequestTimeout:
+    if isinstance(value, tuple):
+        if len(value) != 2:
+            raise ValueError("timeout must be a (connect, read) pair")
+        return (_timeout_seconds(value[0]), _timeout_seconds(value[1]))
+    return _timeout_seconds(value)
 
 
 class Client:
-    def __init__(self, token: str) -> None:
+    def __init__(
+        self, token: str, *, timeout: RequestTimeout = _DEFAULT_TIMEOUT
+    ) -> None:
+        self._timeout = _request_timeout(timeout)
         self._token = token
         self._headers = {
             "User-Agent": _user_agent,
             "Content-Type": "application/json",
             "Authorization": f"Bearer {token}",
         }
-        self._base_url = "https://api.mope.sr/api"
+        self._base_url = _BASE_URL
 
     def call_api(
         self,
@@ -59,20 +86,23 @@ class Client:
             data=data,
             json=json_value(json, path="request"),
             headers=self._headers,
+            timeout=self._timeout,
         )
 
 
 class Mope:
-    def __init__(self, token: str) -> None:
+    def __init__(
+        self, token: str, *, timeout: RequestTimeout = _DEFAULT_TIMEOUT
+    ) -> None:
         self._token = token
         self._headers = {
             "User-Agent": _user_agent,
             "Content-Type": "application/json",
             "Authorization": f"Bearer {token}",
         }
-        self.base_url = "https://api.mope.sr/api"
+        self.base_url = _BASE_URL
 
-        self._client = Client(token)
+        self._client = Client(token, timeout=timeout)
 
         self.shop = ShopResource(self._client)
 

mope/errors.py

@@ -0,0 +1,52 @@
+"""Typed details for HTTP errors returned by the Mopé API."""
+
+from typing import Self
+
+from requests import HTTPError, Response
+
+from mope.json import JsonValue, json_integer, json_object, json_string
+
+
+class MopeAPIError(HTTPError):
+    """An HTTP rejection, with validated Mopé error details when available."""
+
+    response: Response | None
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        response: Response | None = None,
+        code: int | None = None,
+        data: JsonValue = None,
+    ) -> None:
+        super().__init__(message, response=response)
+        self.message = message
+        self.code = code
+        self.data = data
+
+    @property
+    def status_code(self) -> int | None:
+        return self.response.status_code if self.response is not None else None
+
+    @classmethod
+    def from_response(cls, response: Response, *, fallback_message: str) -> Self:
+        try:
+            payload = json_object(response.json())
+            # The schema wraps details in "error"; documented examples are unwrapped.
+            details = json_object(payload.get("error", payload), path="error")
+            code = json_integer(details["code"], path="error.code")
+            message = json_string(details["message"], path="error.message")
+        except (TypeError, ValueError, KeyError):
+            return cls(fallback_message, response=response)
+        return cls(message, response=response, code=code, data=details.get("data"))
+
+
+def raise_for_status(response: Response) -> None:
+    """Preserve HTTPError compatibility without letting a bad error body mask it."""
+    try:
+        response.raise_for_status()
+    except HTTPError as error:
+        raise MopeAPIError.from_response(
+            response, fallback_message=str(error)
+        ) from error

mope/resources/shop.py

@@ -1,3 +1,4 @@
+from mope.errors import raise_for_status
 from mope.models.payments import CreatePaymentResponse, CurrencyCode, PaymentRequest
 from mope.transport import ApiTransport
 
@@ -30,7 +31,7 @@ class ShopResource:
                 "redirect_url": redirect_url,
             },
         )
-        response.raise_for_status()
+        raise_for_status(response)
         return CreatePaymentResponse.from_json(response.json())
 
     def get_payment_request(self, payment_id: str) -> PaymentRequest:
@@ -40,5 +41,5 @@ class ShopResource:
 
         endpoint = f"shop/payment_request/{payment_id}"
         response = self._client.call_api("GET", endpoint=endpoint)
-        response.raise_for_status()
+        raise_for_status(response)
         return PaymentRequest.from_json(response.json())

{python_mope-0.3.0.dist-info → python_mope-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mope
-Version: 0.3.0
+Version: 0.3.1
 Summary: A client library for interacting with the Mopé Web Shop API
 Author-email: Lemuel Boyce <lemuel@vokality.com>
 License-Expression: MIT
@@ -52,6 +52,28 @@ mope = Mope(token="test_123")
 mope.shop.get_payment_request(payment_id="123")
 ```
 
+### Timeouts and errors
+
+Requests use a 5-second connect timeout and a 30-second read timeout by default.
+Configure both with `Mope(token="test_123", timeout=(3.0, 15.0))`, or pass a
+single number of seconds to apply to both. `mope.client.Client` accepts the same
+keyword argument. Values must be finite and greater than zero. The read timeout
+limits inactivity between received bytes, not the total duration of a request.
+
+Shop methods raise `mope.errors.MopeAPIError` for HTTP errors. It is a subclass
+of `requests.HTTPError`, so existing handlers keep working. Its `status_code`,
+`code`, `message`, and `data` fields expose the HTTP status and validated Mopé
+error details, such as code `1033` for account limits exceeded. If the error body
+is missing or malformed, `code` and `data` are `None` and `message` retains the
+HTTP error description. The original response and exception cause are preserved.
+
+Connection failures and timeouts remain `requests.RequestException` subclasses.
+Malformed successful responses still raise `TypeError`, `ValueError`, or
+`KeyError`; invalid JSON raises `requests.exceptions.JSONDecodeError`, which is
+also a `ValueError`. Applications should translate these errors at the API call
+boundary and decide which failures are retryable. Requests are not automatically
+retried, including payment creation after a timeout.
+
 ### Development
 
 Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then run:

python_mope-0.3.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+mope/__init__.py,sha256=3nuq9PuAWTDZz6Ejg_737iQ5JRSC44uW_n5NPdHUscU,49
+mope/__version__.py,sha256=nPR1XtJJZHIxfooRzFILzYZoEY8yB6SRqip56TzwbZQ,57
+mope/client.py,sha256=gzVm5bwrXC1E8EzujzXys_yekAEF19HNhDAUY9nuYs4,3197
+mope/errors.py,sha256=Tw3jJIZLbVchjyklLZrTCvizQhqqWiN9DRXufXiPTg8,1798
+mope/json.py,sha256=kj03cwke1AXfd3LjFygapfYeopavF_e6YuasRMLamRE,1625
+mope/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mope/transport.py,sha256=AuN6SaKZG13d8ujVNOzMrSNMttH3P6Gl6x9hfznfoew,255
+mope/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mope/models/payments.py,sha256=oKovsudX6OvaTib4ya-GikuMDwvQVkDB-0pvSQyF-6I,3204
+mope/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mope/resources/shop.py,sha256=yCkzIkE9d01W87-3RZQQ1OphVoWje79BLKPQ7GMNgTM,1379
+python_mope-0.3.1.dist-info/licenses/LICENSE,sha256=H1HkxgxLo4v8voMaHpZVRh5Ao8jUezeLzSHpp182his,1069
+python_mope-0.3.1.dist-info/METADATA,sha256=xpxImo4Eg_-rem1cADBj_YyFY3MhCT6OLV_iAZKv7HY,5401
+python_mope-0.3.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+python_mope-0.3.1.dist-info/top_level.txt,sha256=KNJibHVOvmp47d34dVOoxczy3_oafEiKZ4szVTOW6AA,5
+python_mope-0.3.1.dist-info/RECORD,,

python_mope-0.3.0.dist-info/RECORD

@@ -1,15 +0,0 @@
-mope/__init__.py,sha256=3nuq9PuAWTDZz6Ejg_737iQ5JRSC44uW_n5NPdHUscU,49
-mope/__version__.py,sha256=m1lfA5cU5lKTRV_7jofTAXIaBSOm8FGd8VLnnfV4jug,57
-mope/client.py,sha256=WK8IPinJu84GsxsDC3vDzGB3c8wcjFEisMtaCq8IID8,2074
-mope/json.py,sha256=kj03cwke1AXfd3LjFygapfYeopavF_e6YuasRMLamRE,1625
-mope/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mope/transport.py,sha256=AuN6SaKZG13d8ujVNOzMrSNMttH3P6Gl6x9hfznfoew,255
-mope/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mope/models/payments.py,sha256=oKovsudX6OvaTib4ya-GikuMDwvQVkDB-0pvSQyF-6I,3204
-mope/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mope/resources/shop.py,sha256=qQfDCbOOFJmIbii6bqpUOlg4npjUiJFqEd7nLeKu4Hc,1340
-python_mope-0.3.0.dist-info/licenses/LICENSE,sha256=H1HkxgxLo4v8voMaHpZVRh5Ao8jUezeLzSHpp182his,1069
-python_mope-0.3.0.dist-info/METADATA,sha256=JPw6Ao0bgzNLk3sPKznoSw3nK_G9VjKq8_Vuhf7TOLc,4046
-python_mope-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
-python_mope-0.3.0.dist-info/top_level.txt,sha256=KNJibHVOvmp47d34dVOoxczy3_oafEiKZ4szVTOW6AA,5
-python_mope-0.3.0.dist-info/RECORD,,