nomba-python 0.1.0__py3-none-any.whl

nomba_python/__init__.py

@@ -0,0 +1,40 @@
+from .client import AsyncNomba, Nomba
+from .concurrency import gather_limited
+from .exceptions import (
+    NombaAPIError,
+    NombaAuthError,
+    NombaError,
+    NombaValidationError,
+)
+from .flows import AsyncCardPaymentFlow, CardPaymentFlow, CardPaymentStep
+from .http import AsyncNombaClient, NombaClient
+from .pagination import apaginate, paginate
+from .webhooks import (
+    check_timestamp_freshness,
+    compute_signature,
+    verify_webhook_request,
+    verify_webhook_signature,
+)
+
+__all__ = [
+    "Nomba",
+    "AsyncNomba",
+    "NombaClient",
+    "AsyncNombaClient",
+    "NombaError",
+    "NombaAPIError",
+    "NombaAuthError",
+    "NombaValidationError",
+    "CardPaymentFlow",
+    "AsyncCardPaymentFlow",
+    "CardPaymentStep",
+    "paginate",
+    "apaginate",
+    "gather_limited",
+    "verify_webhook_signature",
+    "verify_webhook_request",
+    "compute_signature",
+    "check_timestamp_freshness",
+]
+
+__version__ = "0.1.0"

nomba_python/client.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from .http import AsyncNombaClient, NombaClient
+from .resources import (
+    Accounts,
+    AirtimeData,
+    AsyncAccounts,
+    AsyncAirtimeData,
+    AsyncCableTv,
+    AsyncCharge,
+    AsyncCheckout,
+    AsyncElectricity,
+    AsyncTerminals,
+    AsyncTransactions,
+    AsyncTransfers,
+    AsyncVirtualAccounts,
+    CableTv,
+    Charge,
+    Checkout,
+    Electricity,
+    Terminals,
+    Transactions,
+    Transfers,
+    VirtualAccounts,
+)
+from .flows import CardPaymentFlow, AsyncCardPaymentFlow
+
+
+class Nomba:
+    """
+    High-level entry point for the Nomba SDK. Covers every endpoint in
+    Nomba's published OpenAPI spec.
+
+    Example:
+        from nomba import Nomba
+
+        nomba = Nomba(
+            client_id="...",
+            client_secret="...",
+            account_id="...",
+            sandbox=True,
+        )
+
+        account = nomba.virtual_accounts.create_virtual_account(
+            account_ref="ref-123",
+            account_name="Jane Doe",
+        )
+
+    Resource groups:
+        accounts, virtual_accounts, checkout, charge, transfers,
+        terminals, transactions, airtime_data, cabletv, electricity
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        account_id: str,
+        *,
+        sandbox: bool = False,
+        timeout: float = 30.0,
+    ) -> None:
+        self.client = NombaClient(
+            client_id=client_id,
+            client_secret=client_secret,
+            account_id=account_id,
+            sandbox=sandbox,
+            timeout=timeout,
+        )
+        self.accounts = Accounts(self.client)
+        self.virtual_accounts = VirtualAccounts(self.client)
+        self.checkout = Checkout(self.client)
+        self.charge = Charge(self.client)
+        self.transfers = Transfers(self.client)
+        self.terminals = Terminals(self.client)
+        self.transactions = Transactions(self.client)
+        self.airtime_data = AirtimeData(self.client)
+        self.cabletv = CableTv(self.client)
+        self.electricity = Electricity(self.client)
+
+    def close(self) -> None:
+        self.client.close()
+
+    def card_payment(self, order_reference: str) -> "CardPaymentFlow":
+        """Start a guided card-payment flow for an existing checkout order.
+        See `nomba.flows.CardPaymentFlow` for the full step-by-step API."""
+        from .flows import CardPaymentFlow
+
+        return CardPaymentFlow(self.charge, order_reference=order_reference)
+
+    def __enter__(self) -> "Nomba":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+
+class AsyncNomba:
+    """
+    Async high-level entry point for the Nomba SDK (uses httpx.AsyncClient).
+    Covers every endpoint in Nomba's published OpenAPI spec.
+
+    Example:
+        from nomba import AsyncNomba
+
+        async def main():
+            nomba = AsyncNomba(
+                client_id="...",
+                client_secret="...",
+                account_id="...",
+                sandbox=True,
+            )
+            account = await nomba.virtual_accounts.create_virtual_account(
+                account_ref="ref-123",
+                account_name="Jane Doe",
+            )
+            await nomba.close()
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        account_id: str,
+        *,
+        sandbox: bool = False,
+        timeout: float = 30.0,
+    ) -> None:
+        self.client = AsyncNombaClient(
+            client_id=client_id,
+            client_secret=client_secret,
+            account_id=account_id,
+            sandbox=sandbox,
+            timeout=timeout,
+        )
+        self.accounts = AsyncAccounts(self.client)
+        self.virtual_accounts = AsyncVirtualAccounts(self.client)
+        self.checkout = AsyncCheckout(self.client)
+        self.charge = AsyncCharge(self.client)
+        self.transfers = AsyncTransfers(self.client)
+        self.terminals = AsyncTerminals(self.client)
+        self.transactions = AsyncTransactions(self.client)
+        self.airtime_data = AsyncAirtimeData(self.client)
+        self.cabletv = AsyncCableTv(self.client)
+        self.electricity = AsyncElectricity(self.client)
+
+    async def close(self) -> None:
+        await self.client.close()
+
+    def card_payment(self, order_reference: str) -> "AsyncCardPaymentFlow":
+        """Start a guided async card-payment flow for an existing checkout
+        order. See `nomba.flows.AsyncCardPaymentFlow` for the full API."""
+        from .flows import AsyncCardPaymentFlow
+
+        return AsyncCardPaymentFlow(self.charge, order_reference=order_reference)
+
+    async def __aenter__(self) -> "AsyncNomba":
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.close()

nomba_python/concurrency.py

@@ -0,0 +1,54 @@
+"""
+Bounded concurrency helper.
+
+`asyncio.gather` has no built-in concurrency limit -- firing off 200 async
+calls with `asyncio.gather(*[nomba.transfers.send(...) for ...])` sends all
+200 at once. If several start failing (e.g. Nomba rate-limiting you), each
+one independently retries with its own backoff, multiplying load right when
+the API is already struggling, and you may also just trip the rate limit by
+bursting too many requests in the same window.
+
+`gather_limited` runs the same calls but caps how many are in flight at
+once, which keeps both the retry storm and the burst size bounded.
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Awaitable, Callable, Sequence, TypeVar
+
+T = TypeVar("T")
+
+
+async def gather_limited(
+    calls: Sequence[Callable[[], Awaitable[T]]],
+    *,
+    limit: int = 5,
+    return_exceptions: bool = False,
+) -> list[T| BaseException]:
+    """
+    Run a sequence of zero-arg async callables with at most `limit` running
+    concurrently, preserving input order in the returned results.
+
+    Example:
+        from nomba import AsyncNomba
+        from nomba.concurrency import gather_limited
+
+        async with AsyncNomba(...) as nomba:
+            calls = [
+                (lambda ref=ref: nomba.virtual_accounts.fetch_a_virtual_account(ref))
+                for ref in account_refs
+            ]
+            results = await gather_limited(calls, limit=5)
+
+    `return_exceptions=True` behaves like `asyncio.gather(..., return_exceptions=True)`:
+    exceptions are returned in place of results instead of propagating.
+    """
+    semaphore = asyncio.Semaphore(limit)
+
+    async def _run(call: Callable[[], Awaitable[T]]) -> T:
+        async with semaphore:
+            return await call()
+
+    return await asyncio.gather(
+        *(_run(call) for call in calls), return_exceptions=return_exceptions
+    )