python-myanmar-payments 4.0.0a1__py3-none-any.whl

python_myanmar_payments/_facade.py

@@ -0,0 +1,271 @@
+"""Builds every gateway from one configuration (or the environment)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from types import TracebackType
+from typing import Any, TypeVar
+
+import httpx
+
+from ._cache import AsyncTokenCache, MemoryTokenCache, TokenCache
+from ._errors import ConfigurationError
+from ._http import DEFAULT_TIMEOUT
+from ._support import EnvSource, config_of
+from .aya_pay import AsyncAyaPay, AyaPay, AyaPayConfig
+from .cyber_source import CyberSource, CyberSourceConfig
+from .kbz_pay import AsyncKbzPay, KbzPay, KbzPayConfig
+from .wave_money import AsyncWaveMoney, WaveMoney, WaveMoneyConfig
+from .yoma_mmqr import AsyncYomaMmqr, YomaMmqr, YomaMmqrConfig
+
+__all__ = ["AsyncMyanmarPayments", "MyanmarPayments"]
+
+_C = TypeVar("_C")
+
+
+def _lazy(config_class: type[_C], config: _C | Mapping[str, Any] | None) -> Callable[[], _C] | None:
+    return None if config is None else lambda: config_of(config_class, config)
+
+
+def _resolve(source: Callable[[], _C] | None, gateway: str, first_key: str) -> _C:
+    if source is None:
+        raise ConfigurationError(gateway, first_key)
+    return source()
+
+
+class _Payments:
+    """Holds each gateway's configuration until the gateway is first used."""
+
+    def __init__(
+        self,
+        kbz_pay: KbzPayConfig | Mapping[str, Any] | None,
+        wave_money: WaveMoneyConfig | Mapping[str, Any] | None,
+        aya_pay: AyaPayConfig | Mapping[str, Any] | None,
+        yoma_mmqr: YomaMmqrConfig | Mapping[str, Any] | None,
+        cyber_source: CyberSourceConfig | Mapping[str, Any] | None,
+        timeout: float | None,
+    ) -> None:
+        self._kbz_pay_config = _lazy(KbzPayConfig, kbz_pay)
+        self._wave_money_config = _lazy(WaveMoneyConfig, wave_money)
+        self._aya_pay_config = _lazy(AyaPayConfig, aya_pay)
+        self._yoma_mmqr_config = _lazy(YomaMmqrConfig, yoma_mmqr)
+        self._cyber_source_config = _lazy(CyberSourceConfig, cyber_source)
+        self._timeout = timeout
+        self._cyber_source: CyberSource | None = None
+
+    def _read_env(self, env: EnvSource | None) -> None:
+        self._kbz_pay_config = lambda: KbzPayConfig.from_env(env)
+        self._wave_money_config = lambda: WaveMoneyConfig.from_env(env)
+        self._aya_pay_config = lambda: AyaPayConfig.from_env(env)
+        self._yoma_mmqr_config = lambda: YomaMmqrConfig.from_env(env)
+        self._cyber_source_config = lambda: CyberSourceConfig.from_env(env)
+
+    def cyber_source(self) -> CyberSource:
+        """The CyberSource gateway. Raises a ``ConfigurationError`` when not configured."""
+        if self._cyber_source is None:
+            config = _resolve(self._cyber_source_config, "cyber_source", "profile_id")
+            self._cyber_source = CyberSource(config)
+        return self._cyber_source
+
+
+class MyanmarPayments(_Payments):
+    """Builds each gateway (sync clients) from one configuration or the environment.
+
+    Gateways are created on first use and reused, so only the gateways you call
+    need to be configured. Create it once and share it; :meth:`close` (or a
+    ``with`` block) closes the HTTP clients it created.
+    """
+
+    def __init__(
+        self,
+        *,
+        kbz_pay: KbzPayConfig | Mapping[str, Any] | None = None,
+        wave_money: WaveMoneyConfig | Mapping[str, Any] | None = None,
+        aya_pay: AyaPayConfig | Mapping[str, Any] | None = None,
+        yoma_mmqr: YomaMmqrConfig | Mapping[str, Any] | None = None,
+        cyber_source: CyberSourceConfig | Mapping[str, Any] | None = None,
+        token_cache: TokenCache | None = None,
+        http_client: httpx.Client | None = None,
+        timeout: float | None = DEFAULT_TIMEOUT,
+    ) -> None:
+        super().__init__(kbz_pay, wave_money, aya_pay, yoma_mmqr, cyber_source, timeout)
+        self._http_client = http_client
+        self._token_cache: TokenCache = (
+            token_cache if token_cache is not None else MemoryTokenCache()
+        )
+        self._kbz_pay: KbzPay | None = None
+        self._wave_money: WaveMoney | None = None
+        self._aya_pay: AyaPay | None = None
+        self._yoma_mmqr: YomaMmqr | None = None
+
+    @classmethod
+    def from_env(
+        cls,
+        env: EnvSource | None = None,
+        *,
+        token_cache: TokenCache | None = None,
+        http_client: httpx.Client | None = None,
+        timeout: float | None = DEFAULT_TIMEOUT,
+    ) -> MyanmarPayments:
+        """Reads every gateway's configuration from environment variables.
+
+        ``KBZ_PAY_*``, ``WAVE_MONEY_*``, ``AYA_PAY_*``, ``YOMA_MMQR_*`` and
+        ``CYBER_SOURCE_*`` are read when the gateway is first used. Defaults to
+        ``os.environ``.
+        """
+        payments = cls(token_cache=token_cache, http_client=http_client, timeout=timeout)
+        payments._read_env(env)
+        return payments
+
+    def kbz_pay(self) -> KbzPay:
+        """The KBZ Pay gateway. Raises a ``ConfigurationError`` when not configured."""
+        if self._kbz_pay is None:
+            config = _resolve(self._kbz_pay_config, "kbz_pay", "app_id")
+            self._kbz_pay = KbzPay(config, http_client=self._http_client, timeout=self._timeout)
+        return self._kbz_pay
+
+    def wave_money(self) -> WaveMoney:
+        """The Wave Money gateway. Raises a ``ConfigurationError`` when not configured."""
+        if self._wave_money is None:
+            config = _resolve(self._wave_money_config, "wave_money", "merchant_id")
+            self._wave_money = WaveMoney(
+                config, http_client=self._http_client, timeout=self._timeout
+            )
+        return self._wave_money
+
+    def aya_pay(self) -> AyaPay:
+        """The AYA Payment Gateway. Raises a ``ConfigurationError`` when not configured."""
+        if self._aya_pay is None:
+            config = _resolve(self._aya_pay_config, "aya_pay", "app_key")
+            self._aya_pay = AyaPay(config, http_client=self._http_client, timeout=self._timeout)
+        return self._aya_pay
+
+    def yoma_mmqr(self) -> YomaMmqr:
+        """The Yoma MMQR gateway. Raises a ``ConfigurationError`` when not configured."""
+        if self._yoma_mmqr is None:
+            config = _resolve(self._yoma_mmqr_config, "yoma_mmqr", "merchant_id")
+            self._yoma_mmqr = YomaMmqr(
+                config,
+                token_cache=self._token_cache,
+                http_client=self._http_client,
+                timeout=self._timeout,
+            )
+        return self._yoma_mmqr
+
+    def close(self) -> None:
+        """Closes the HTTP clients the gateways created. A client you passed stays open."""
+        for gateway in (self._kbz_pay, self._wave_money, self._aya_pay, self._yoma_mmqr):
+            if gateway is not None:
+                gateway.close()
+
+    def __enter__(self) -> MyanmarPayments:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncMyanmarPayments(_Payments):
+    """Builds each gateway (async clients) from one configuration or the environment.
+
+    The async twin of :class:`MyanmarPayments`: ``kbz_pay()`` returns an
+    :class:`AsyncKbzPay` and so on. :meth:`aclose` (or an ``async with`` block)
+    closes the HTTP clients it created.
+    """
+
+    def __init__(
+        self,
+        *,
+        kbz_pay: KbzPayConfig | Mapping[str, Any] | None = None,
+        wave_money: WaveMoneyConfig | Mapping[str, Any] | None = None,
+        aya_pay: AyaPayConfig | Mapping[str, Any] | None = None,
+        yoma_mmqr: YomaMmqrConfig | Mapping[str, Any] | None = None,
+        cyber_source: CyberSourceConfig | Mapping[str, Any] | None = None,
+        token_cache: TokenCache | AsyncTokenCache | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        timeout: float | None = DEFAULT_TIMEOUT,
+    ) -> None:
+        super().__init__(kbz_pay, wave_money, aya_pay, yoma_mmqr, cyber_source, timeout)
+        self._http_client = http_client
+        self._token_cache: TokenCache | AsyncTokenCache = (
+            token_cache if token_cache is not None else MemoryTokenCache()
+        )
+        self._kbz_pay: AsyncKbzPay | None = None
+        self._wave_money: AsyncWaveMoney | None = None
+        self._aya_pay: AsyncAyaPay | None = None
+        self._yoma_mmqr: AsyncYomaMmqr | None = None
+
+    @classmethod
+    def from_env(
+        cls,
+        env: EnvSource | None = None,
+        *,
+        token_cache: TokenCache | AsyncTokenCache | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        timeout: float | None = DEFAULT_TIMEOUT,
+    ) -> AsyncMyanmarPayments:
+        """Reads every gateway's configuration from environment variables on first use."""
+        payments = cls(token_cache=token_cache, http_client=http_client, timeout=timeout)
+        payments._read_env(env)
+        return payments
+
+    def kbz_pay(self) -> AsyncKbzPay:
+        """The KBZ Pay gateway. Raises a ``ConfigurationError`` when not configured."""
+        if self._kbz_pay is None:
+            config = _resolve(self._kbz_pay_config, "kbz_pay", "app_id")
+            self._kbz_pay = AsyncKbzPay(
+                config, http_client=self._http_client, timeout=self._timeout
+            )
+        return self._kbz_pay
+
+    def wave_money(self) -> AsyncWaveMoney:
+        """The Wave Money gateway. Raises a ``ConfigurationError`` when not configured."""
+        if self._wave_money is None:
+            config = _resolve(self._wave_money_config, "wave_money", "merchant_id")
+            self._wave_money = AsyncWaveMoney(
+                config, http_client=self._http_client, timeout=self._timeout
+            )
+        return self._wave_money
+
+    def aya_pay(self) -> AsyncAyaPay:
+        """The AYA Payment Gateway. Raises a ``ConfigurationError`` when not configured."""
+        if self._aya_pay is None:
+            config = _resolve(self._aya_pay_config, "aya_pay", "app_key")
+            self._aya_pay = AsyncAyaPay(
+                config, http_client=self._http_client, timeout=self._timeout
+            )
+        return self._aya_pay
+
+    def yoma_mmqr(self) -> AsyncYomaMmqr:
+        """The Yoma MMQR gateway. Raises a ``ConfigurationError`` when not configured."""
+        if self._yoma_mmqr is None:
+            config = _resolve(self._yoma_mmqr_config, "yoma_mmqr", "merchant_id")
+            self._yoma_mmqr = AsyncYomaMmqr(
+                config,
+                token_cache=self._token_cache,
+                http_client=self._http_client,
+                timeout=self._timeout,
+            )
+        return self._yoma_mmqr
+
+    async def aclose(self) -> None:
+        """Closes the HTTP clients the gateways created. A client you passed stays open."""
+        for gateway in (self._kbz_pay, self._wave_money, self._aya_pay, self._yoma_mmqr):
+            if gateway is not None:
+                await gateway.aclose()
+
+    async def __aenter__(self) -> AsyncMyanmarPayments:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()

python_myanmar_payments/_http.py

@@ -0,0 +1,201 @@
+"""Sends the gateways' HTTP requests with httpx, sync or async."""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import TracebackType
+from typing import Any, TypeVar
+from urllib.parse import urlencode
+
+import httpx
+
+from ._errors import ApiError
+from ._json import LosslessObject, dumps, parse_object
+
+DEFAULT_TIMEOUT = 30.0
+"""The default request timeout, in seconds."""
+
+
+@dataclass(frozen=True)
+class HttpRequest:
+    """A request a gateway sends. Gateways only send ``POST`` requests."""
+
+    url: str
+    body: str
+    headers: Mapping[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class GatewayResponse:
+    """A gateway's response: its status and raw body text."""
+
+    status: int
+    body: str
+
+    def successful(self) -> bool:
+        return 200 <= self.status < 300
+
+    def json(self) -> LosslessObject:
+        """The body as a JSON object with exact numbers, or ``{}`` when it is not one."""
+        return parse_object(self.body) or {}
+
+
+def json_request(
+    url: str, data: Mapping[str, Any], headers: Mapping[str, str] | None = None
+) -> HttpRequest:
+    return HttpRequest(
+        url=url,
+        body=dumps(data),
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            **(headers or {}),
+        },
+    )
+
+
+def form_request(
+    url: str, data: Mapping[str, str], headers: Mapping[str, str] | None = None
+) -> HttpRequest:
+    return HttpRequest(
+        url=url,
+        body=urlencode(data),
+        headers={
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Accept": "application/json",
+            **(headers or {}),
+        },
+    )
+
+
+def _unreachable(request: HttpRequest, error: Exception) -> ApiError:
+    return ApiError(f"Could not reach {request.url}: {str(error) or type(error).__name__}")
+
+
+def _response(response: httpx.Response) -> GatewayResponse:
+    return GatewayResponse(response.status_code, response.content.decode("utf-8", "replace"))
+
+
+class SyncTransport:
+    """Posts requests with an ``httpx.Client``, created on first use unless given."""
+
+    def __init__(self, client: httpx.Client | None, timeout: float | None) -> None:
+        self._client = client
+        self._owns_client = client is None
+        self._timeout = timeout
+        self._lock = threading.Lock()
+
+    def send(self, request: HttpRequest) -> GatewayResponse:
+        try:
+            response = self._http().post(
+                request.url, content=request.body.encode(), headers=dict(request.headers)
+            )
+        except Exception as error:
+            raise _unreachable(request, error) from error
+        return _response(response)
+
+    def _http(self) -> httpx.Client:
+        with self._lock:
+            if self._client is None:
+                self._client = httpx.Client(timeout=self._timeout)
+            return self._client
+
+    def close(self) -> None:
+        """Closes the client this transport created; a client you passed stays open."""
+        with self._lock:
+            if self._owns_client and self._client is not None:
+                self._client.close()
+                self._client = None
+
+
+class AsyncTransport:
+    """Posts requests with an ``httpx.AsyncClient``, created on first use unless given."""
+
+    def __init__(self, client: httpx.AsyncClient | None, timeout: float | None) -> None:
+        self._client = client
+        self._owns_client = client is None
+        self._timeout = timeout
+
+    async def send(self, request: HttpRequest) -> GatewayResponse:
+        try:
+            response = await self._http().post(
+                request.url, content=request.body.encode(), headers=dict(request.headers)
+            )
+        except Exception as error:
+            raise _unreachable(request, error) from error
+        return _response(response)
+
+    def _http(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=self._timeout)
+        return self._client
+
+    async def aclose(self) -> None:
+        """Closes the client this transport created; a client you passed stays open."""
+        if self._owns_client and self._client is not None:
+            client, self._client = self._client, None
+            await client.aclose()
+
+
+_S = TypeVar("_S", bound="SyncGateway")
+_A = TypeVar("_A", bound="AsyncGateway")
+
+
+class SyncGateway:
+    """A gateway that calls its API with a synchronous ``httpx.Client``.
+
+    Pass ``http_client`` to share a client (proxies, tracing, test transports);
+    otherwise one is created on first use with ``timeout`` seconds (default 30)
+    and closed by :meth:`close` or a ``with`` block.
+    """
+
+    _transport: SyncTransport
+
+    def _init_transport(self, http_client: httpx.Client | None, timeout: float | None) -> None:
+        self._transport = SyncTransport(http_client, timeout)
+
+    def close(self) -> None:
+        """Closes the HTTP client the gateway created. A client you passed stays open."""
+        self._transport.close()
+
+    def __enter__(self: _S) -> _S:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncGateway:
+    """A gateway that calls its API with an ``httpx.AsyncClient``.
+
+    Pass ``http_client`` to share a client; otherwise one is created on first use
+    with ``timeout`` seconds (default 30) and closed by :meth:`aclose` or an
+    ``async with`` block.
+    """
+
+    _transport: AsyncTransport
+
+    def _init_transport(self, http_client: httpx.AsyncClient | None, timeout: float | None) -> None:
+        self._transport = AsyncTransport(http_client, timeout)
+
+    async def aclose(self) -> None:
+        """Closes the HTTP client the gateway created. A client you passed stays open."""
+        await self._transport.aclose()
+
+    async def __aenter__(self: _A) -> _A:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()

python_myanmar_payments/_json.py

@@ -0,0 +1,94 @@
+"""Lossless JSON: numbers keep the exact text the gateway sent."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Union
+
+__all__ = [
+    "JsonNumber",
+    "LosslessObject",
+    "LosslessValue",
+    "dumps",
+    "parse_object",
+    "to_plain",
+    "to_plain_object",
+]
+
+
+class JsonNumber:
+    """A JSON number kept as the exact text the gateway sent.
+
+    ``1000.50`` stays ``1000.50`` and large integers keep every digit. Only used
+    internally while verifying signatures and reading values.
+    """
+
+    __slots__ = ("text",)
+
+    def __init__(self, text: str) -> None:
+        self.text = text
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, JsonNumber) and other.text == self.text
+
+    def __hash__(self) -> int:
+        return hash(self.text)
+
+    def __repr__(self) -> str:
+        return f"JsonNumber({self.text!r})"
+
+
+LosslessValue = Union[
+    str, bool, None, JsonNumber, "list[LosslessValue]", "dict[str, LosslessValue]"
+]
+LosslessObject = dict[str, LosslessValue]
+
+
+def _reject_constant(name: str) -> Any:
+    raise ValueError(f"{name} is not valid JSON")
+
+
+def parse_object(text: str) -> LosslessObject | None:
+    """Parses strict JSON (RFC 8259) without passing numbers through a float.
+
+    Returns the object, or ``None`` when the text is not valid JSON or not an
+    object (an array, a string or ``null``).
+    """
+    try:
+        value = json.loads(
+            text,
+            parse_int=JsonNumber,
+            parse_float=JsonNumber,
+            parse_constant=_reject_constant,
+        )
+    except (ValueError, RecursionError):
+        return None
+    return value if isinstance(value, dict) else None
+
+
+def to_plain(value: LosslessValue) -> Any:
+    """Converts a lossless value to plain Python values for the ``raw`` of results.
+
+    Numbers become their exact text as a ``str`` (``1000.50`` stays ``"1000.50"``),
+    never a float.
+    """
+    if isinstance(value, JsonNumber):
+        return value.text
+    if isinstance(value, list):
+        return [to_plain(item) for item in value]
+    if isinstance(value, dict):
+        return to_plain_object(value)
+    return value
+
+
+def to_plain_object(value: LosslessObject) -> dict[str, Any]:
+    """Converts a lossless object to plain Python values."""
+    return {key: to_plain(item) for key, item in value.items()}
+
+
+def dumps(value: Any) -> str:
+    """Compact JSON like JavaScript's ``JSON.stringify``.
+
+    Decimals and amounts are written as strings, so no float is involved.
+    """
+    return json.dumps(value, separators=(",", ":"), ensure_ascii=False, default=str)