reefapi 0.1.0__py3-none-any.whl

reefapi/_errors.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+__all__ = ["ReefAPIError"]
+
+
+class ReefAPIError(Exception):
+    """Raised when a ReefAPI call does not return ``ok: true``.
+
+    Attributes:
+        code: Machine-readable error code from the gateway (``AUTH_FAILED``, ``INVALID_PARAM``,
+            ``MISSING_PARAM``, ``RATE_LIMITED``, ``QUOTA_EXCEEDED``, ``TARGET_BLOCKED``,
+            ``UPSTREAM_TIMEOUT``, ``NOT_FOUND``, ...). Errors raised by the SDK itself use
+            ``TIMEOUT``, ``NETWORK_ERROR``, ``MISSING_API_KEY``, ``INVALID_RESPONSE`` or ``HTTP_<status>``.
+        message: Human-readable explanation.
+        retryable: ``True`` when the same call may succeed if repeated later.
+        status: HTTP status code, or ``None`` when no response was received.
+        request_id: The gateway's ``meta.request_id`` (quote it when contacting support).
+        meta: The response ``meta`` object, if any.
+        details: Optional extra ``error.details`` sent by the gateway.
+
+    Failed calls are not charged.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        retryable: bool = False,
+        status: Optional[int] = None,
+        *,
+        request_id: Optional[str] = None,
+        meta: Optional[Dict[str, Any]] = None,
+        details: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.retryable = retryable
+        self.status = status
+        self.request_id = request_id
+        self.meta: Dict[str, Any] = meta or {}
+        self.details = details
+
+    def __str__(self) -> str:
+        parts = [f"{self.code}: {self.message}"]
+        if self.status is not None:
+            parts.append(f"(HTTP {self.status})")
+        if self.request_id:
+            parts.append(f"[request_id={self.request_id}]")
+        return " ".join(parts)
+
+    def __repr__(self) -> str:
+        return (
+            f"ReefAPIError(code={self.code!r}, message={self.message!r}, "
+            f"retryable={self.retryable!r}, status={self.status!r})"
+        )

reefapi/_types.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Mapping, TypedDict
+
+__all__ = ["ReefResponse", "Category", "ParamSpec", "ActionInfo", "EngineInfo"]
+
+
+@dataclass
+class ReefResponse:
+    """The full envelope of a successful call (``client.call_raw``).
+
+    ``data`` is the payload ``client.call`` returns; ``meta`` carries ``request_id``,
+    ``latency_ms``, ``record_count`` and, for paged actions, ``pagination``.
+    """
+
+    data: Any
+    meta: Dict[str, Any] = field(default_factory=dict)
+    status: int = 200
+    headers: Mapping[str, str] = field(default_factory=dict)
+
+
+class Category(TypedDict, total=False):
+    id: str
+    title: str
+
+
+class ParamSpec(TypedDict, total=False):
+    name: str
+    type: str
+    required: bool
+    description: str
+    default: Any
+    example: Any
+    allowed_values: List[Dict[str, Any]]
+    aliases: List[str]
+    minimum: float
+    maximum: float
+
+
+class ActionInfo(TypedDict, total=False):
+    name: str
+    description: str
+    required_params: List[str]
+    optional_params: List[str]
+    params: List[ParamSpec]
+    example_params: Dict[str, Any]
+    returns: str
+
+
+class EngineInfo(TypedDict, total=False):
+    name: str
+    title: str
+    version: str
+    category: Category
+    base_path: str
+    actions: List[ActionInfo]

reefapi/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"