python-mope 0.1.0__tar.gz → 0.3.1__tar.gz

python_mope-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Lemuel Boyce
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_mope-0.3.1/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: python-mope
+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
+Project-URL: Homepage, https://github.com/rhymiz/python-mope
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 6 - Mature
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.34.2
+Dynamic: license-file
+
+![build](https://github.com/rhymiz/python-mope/workflows/build/badge.svg)
+[![downloads](https://pepy.tech/badge/python-mope)](https://pepy.tech/project/python-mope)
+[![Ruff](https://img.shields.io/badge/lint%20and%20format-Ruff-D7FF64.svg)](https://docs.astral.sh/ruff/)
+
+# Python Mopé
+Client library for Mopé by Hakrinbank
+
+### Token acquisition and API Docs
+- [API Docs](https://api.mope.sr/integration/doc)
+- Instructions for [acquiring a token](https://drive.google.com/file/d/10fWqgpl2Ip9JIacl0pwzUDi_HV6WLbCi/view?usp=sharing)
+
+
+### Requirements
+- Python 3.11 or newer
+- Mopé API Token
+
+### Getting Started
+First, install from PyPi by running `pip install python-mope`
+
+Example usage:
+
+```python
+from mope import Mope
+
+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:
+
+```sh
+uv sync --locked
+uv run --locked ruff check .
+uv run --locked ruff format --check .
+uv run --locked ty check
+uv run --locked pytest
+uv build --no-sources
+```
+
+Development uses Python 3.15.2 from `.python-version`; uv installs it when needed.
+The library supports Python 3.11+, and CI tests the built wheel on Python 3.11,
+3.12, 3.13, 3.14, and 3.15. Ruff and ty target Python 3.11 compatibility.
+Run `uv run ruff format .` to format code. Commit `uv.lock` after changing
+dependencies; use `uv lock --upgrade` to refresh their locked versions.
+
+The package includes inline types and a `py.typed` marker. API responses are
+validated before creating models: invalid field types raise `TypeError`, invalid
+status values raise `ValueError`, and missing required fields raise `KeyError`.
+Values are not coerced. Payment metadata remains a list of dictionaries with
+string `key` and `value` fields, as defined by the
+[Mopé API schema](https://api.mope.sr/integration/paths/GetPaymentRequest.yaml).
+
+### Publishing
+
+To release, update `mope/__version__.py`, run `uv lock`, and commit the changes.
+Publish a GitHub release whose tag is the package version or `v` followed by that
+version. The workflow checks the tag, runs lint, formatting and type checks,
+builds the source distribution and wheel, and tests the installed wheel across
+all supported Python versions before uploading those same artifacts to PyPI.
+
+### Resources
+#### shop
+
+*Methods*
+
+##### `shop.create_payment_request`
+
+| Argument   | Type                | Required |
+| ---        |---                  | ---      |
+|amount      | int                 | yes      |
+|description | string              | yes      |
+|order_id    | string              | yes      |
+|currency    | enum (USD, SRD, EUR) | yes      |
+|redirect_url| string              | yes      |
+
+
+return type: `mope.models.payments.CreatePaymentResponse`
+
+##### `shop.get_payment_request`
+
+| Argument  | Type   | Required |
+|---        |---     |---       |
+|payment_id | string | yes      |
+
+
+return type: `mope.models.payments.PaymentRequest`

python_mope-0.3.1/README.md

@@ -0,0 +1,110 @@
+![build](https://github.com/rhymiz/python-mope/workflows/build/badge.svg)
+[![downloads](https://pepy.tech/badge/python-mope)](https://pepy.tech/project/python-mope)
+[![Ruff](https://img.shields.io/badge/lint%20and%20format-Ruff-D7FF64.svg)](https://docs.astral.sh/ruff/)
+
+# Python Mopé
+Client library for Mopé by Hakrinbank
+
+### Token acquisition and API Docs
+- [API Docs](https://api.mope.sr/integration/doc)
+- Instructions for [acquiring a token](https://drive.google.com/file/d/10fWqgpl2Ip9JIacl0pwzUDi_HV6WLbCi/view?usp=sharing)
+
+
+### Requirements
+- Python 3.11 or newer
+- Mopé API Token
+
+### Getting Started
+First, install from PyPi by running `pip install python-mope`
+
+Example usage:
+
+```python
+from mope import Mope
+
+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:
+
+```sh
+uv sync --locked
+uv run --locked ruff check .
+uv run --locked ruff format --check .
+uv run --locked ty check
+uv run --locked pytest
+uv build --no-sources
+```
+
+Development uses Python 3.15.2 from `.python-version`; uv installs it when needed.
+The library supports Python 3.11+, and CI tests the built wheel on Python 3.11,
+3.12, 3.13, 3.14, and 3.15. Ruff and ty target Python 3.11 compatibility.
+Run `uv run ruff format .` to format code. Commit `uv.lock` after changing
+dependencies; use `uv lock --upgrade` to refresh their locked versions.
+
+The package includes inline types and a `py.typed` marker. API responses are
+validated before creating models: invalid field types raise `TypeError`, invalid
+status values raise `ValueError`, and missing required fields raise `KeyError`.
+Values are not coerced. Payment metadata remains a list of dictionaries with
+string `key` and `value` fields, as defined by the
+[Mopé API schema](https://api.mope.sr/integration/paths/GetPaymentRequest.yaml).
+
+### Publishing
+
+To release, update `mope/__version__.py`, run `uv lock`, and commit the changes.
+Publish a GitHub release whose tag is the package version or `v` followed by that
+version. The workflow checks the tag, runs lint, formatting and type checks,
+builds the source distribution and wheel, and tests the installed wheel across
+all supported Python versions before uploading those same artifacts to PyPI.
+
+### Resources
+#### shop
+
+*Methods*
+
+##### `shop.create_payment_request`
+
+| Argument   | Type                | Required |
+| ---        |---                  | ---      |
+|amount      | int                 | yes      |
+|description | string              | yes      |
+|order_id    | string              | yes      |
+|currency    | enum (USD, SRD, EUR) | yes      |
+|redirect_url| string              | yes      |
+
+
+return type: `mope.models.payments.CreatePaymentResponse`
+
+##### `shop.get_payment_request`
+
+| Argument  | Type   | Required |
+|---        |---     |---       |
+|payment_id | string | yes      |
+
+
+return type: `mope.models.payments.PaymentRequest`

{python-mope-0.1.0 → python_mope-0.3.1}/mope/__version__.py

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

python_mope-0.3.1/mope/client.py

@@ -0,0 +1,110 @@
+from collections.abc import Iterable, Mapping, Set
+from math import isfinite
+from typing import IO, Protocol, TypeAlias
+from urllib.parse import urljoin
+
+import requests
+
+from mope.__version__ import __version__
+from mope.json import json_value
+from mope.resources.shop import ShopResource
+
+QueryScalar: TypeAlias = str | bytes | int | float
+QueryValue: TypeAlias = QueryScalar | Iterable[QueryScalar] | None
+
+
+class QueryItems(Protocol):
+    def items(self) -> Set[tuple[QueryScalar, QueryValue]]: ...
+
+
+QueryParams: TypeAlias = (
+    QueryItems | Iterable[tuple[QueryScalar, QueryValue]] | str | bytes
+)
+RequestData: TypeAlias = (
+    Mapping[str, object]
+    | list[tuple[str, object]]
+    | tuple[tuple[str, object], ...]
+    | Iterable[bytes]
+    | IO[str]
+    | IO[bytes]
+    | 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, *, 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 = _BASE_URL
+
+    def call_api(
+        self,
+        method: str,
+        endpoint: str,
+        params: QueryParams | None = None,
+        data: RequestData | None = None,
+        json: object = None,
+    ) -> requests.Response:
+        url = urljoin(self._base_url, endpoint)
+        return requests.request(
+            method=method,
+            url=url,
+            params=params,
+            data=data,
+            json=json_value(json, path="request"),
+            headers=self._headers,
+            timeout=self._timeout,
+        )
+
+
+class Mope:
+    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 = _BASE_URL
+
+        self._client = Client(token, timeout=timeout)
+
+        self.shop = ShopResource(self._client)
+
+    def __str__(self) -> str:
+        return _user_agent

python_mope-0.3.1/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

python_mope-0.3.1/mope/json.py

@@ -0,0 +1,49 @@
+"""JSON types and validation at the API boundary."""
+
+from math import isfinite
+from typing import TypeAlias
+
+JsonValue: TypeAlias = (
+    str | int | float | bool | None | list["JsonValue"] | dict[str, "JsonValue"]
+)
+JsonObject: TypeAlias = dict[str, JsonValue]
+
+
+def json_value(value: object, *, path: str = "response") -> JsonValue:
+    if value is None or isinstance(value, (str, bool, int)):
+        return value
+    if isinstance(value, float):
+        if not isfinite(value):
+            raise ValueError(f"{path} must contain a finite JSON number")
+        return value
+    if isinstance(value, list):
+        return [
+            json_value(item, path=f"{path}[{index}]")
+            for index, item in enumerate(value)
+        ]
+    if isinstance(value, dict):
+        return json_object(value, path=path)
+    raise TypeError(f"{path} must be a JSON value")
+
+
+def json_object(value: object, *, path: str = "response") -> JsonObject:
+    if not isinstance(value, dict):
+        raise TypeError(f"{path} must be a JSON object")
+    result: JsonObject = {}
+    for key, item in value.items():
+        if not isinstance(key, str):
+            raise TypeError(f"{path} must have string keys")
+        result[key] = json_value(item, path=f"{path}.{key}")
+    return result
+
+
+def json_string(value: object, *, path: str) -> str:
+    if not isinstance(value, str):
+        raise TypeError(f"{path} must be a string")
+    return value
+
+
+def json_integer(value: object, *, path: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"{path} must be an integer")
+    return value

python_mope-0.3.1/mope/models/payments.py

@@ -0,0 +1,110 @@
+from abc import ABC, abstractmethod
+from dataclasses import asdict, dataclass
+from typing import Literal, Self, TypeAlias, TypedDict
+
+from mope.json import JsonValue, json_integer, json_object, json_string
+
+CurrencyCode: TypeAlias = Literal["SRD", "EUR", "USD"]
+PaymentStatus: TypeAlias = Literal["open", "scanned", "unconfirmed", "paid"]
+
+
+class PaymentMetadata(TypedDict):
+    key: str
+    value: str
+
+
+def _payment_status(value: object) -> PaymentStatus:
+    match value:
+        case "open":
+            return "open"
+        case "scanned":
+            return "scanned"
+        case "unconfirmed":
+            return "unconfirmed"
+        case "paid":
+            return "paid"
+        case _:
+            raise ValueError("status must be open, scanned, unconfirmed, or paid")
+
+
+def _payment_metadata(value: object) -> list[PaymentMetadata]:
+    if not isinstance(value, list):
+        raise TypeError("meta_data must be an array")
+    result: list[PaymentMetadata] = []
+    for index, entry in enumerate(value):
+        path = f"meta_data[{index}]"
+        item = json_object(entry, path=path)
+        result.append(
+            PaymentMetadata(
+                key=json_string(item["key"], path=f"{path}.key"),
+                value=json_string(item["value"], path=f"{path}.value"),
+            )
+        )
+    return result
+
+
+@dataclass
+class BaseModel(ABC):
+    @classmethod
+    @abstractmethod
+    def from_json(cls, data: object) -> Self:
+        pass
+
+    def as_dict(self) -> dict[str, JsonValue]:
+        return json_object(asdict(self))
+
+
+@dataclass
+class CreatePaymentResponse(BaseModel):
+    id: str
+    url: str
+
+    @classmethod
+    def from_json(cls, data: object) -> Self:
+        payload = json_object(data)
+        return cls(
+            id=json_string(payload["id"], path="id"),
+            url=json_string(payload["url"], path="url"),
+        )
+
+
+@dataclass
+class Currency(BaseModel):
+    name: str
+    code: str
+    symbol: str
+
+    @classmethod
+    def from_json(cls, data: object) -> Self:
+        payload = json_object(data, path="currency")
+        return cls(
+            name=json_string(payload["name"], path="currency.name"),
+            code=json_string(payload["code"], path="currency.code"),
+            symbol=json_string(payload["symbol"], path="currency.symbol"),
+        )
+
+
+@dataclass
+class PaymentRequest(BaseModel):
+    id: str
+    amount: int
+    created_at: str
+    description: str
+    expires_at: str
+    currency: Currency
+    status: PaymentStatus
+    meta_data: list[PaymentMetadata]
+
+    @classmethod
+    def from_json(cls, data: object) -> Self:
+        payload = json_object(data)
+        return cls(
+            id=json_string(payload["id"], path="id"),
+            amount=json_integer(payload["amount"], path="amount"),
+            created_at=json_string(payload["created_at"], path="created_at"),
+            description=json_string(payload["description"], path="description"),
+            expires_at=json_string(payload["expires_at"], path="expires_at"),
+            currency=Currency.from_json(payload["currency"]),
+            status=_payment_status(payload["status"]),
+            meta_data=_payment_metadata(payload["meta_data"]),
+        )

{python-mope-0.1.0 → python_mope-0.3.1}/mope/resources/shop.py

@@ -1,8 +1,10 @@
-from mope.models.payments import CreatePaymentResponse, PaymentRequest
+from mope.errors import raise_for_status
+from mope.models.payments import CreatePaymentResponse, CurrencyCode, PaymentRequest
+from mope.transport import ApiTransport
 
 
 class ShopResource:
-    def __init__(self, client) -> None:
+    def __init__(self, client: ApiTransport) -> None:
         self._client = client
 
     def create_payment_request(
@@ -10,7 +12,7 @@ class ShopResource:
         amount: int,
         description: str,
         order_id: str,
-        currency: str,
+        currency: CurrencyCode,
         redirect_url: str,
     ) -> CreatePaymentResponse:
         """
@@ -29,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:
@@ -37,7 +39,7 @@ class ShopResource:
         fetches a payment request given a payment ID
         """
 
-        endpoint = "shop/payment_request/%s" % payment_id
+        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.1/mope/transport.py

@@ -0,0 +1,11 @@
+from typing import Protocol
+
+from requests import Response
+
+
+class ApiTransport(Protocol):
+    """The HTTP operations required by API resources."""
+
+    def call_api(
+        self, method: str, endpoint: str, *, json: object = None
+    ) -> Response: ...