@shoalrun/cli 0.1.0-beta.1 → 1.0.0

package/examples/code-references/python/orchard/errors.py

@@ -0,0 +1,31 @@
+"""Typed errors an application can handle without inspecting error messages."""
+
+class APIError(Exception):
+    """Base error for unsuccessful API operations.
+
+    Handle a more specific exception when your application can recover from it.
+    Use `request_id` when reporting a failed request to an operator.
+    """
+    def __init__(self, message: str, *, request_id: str | None = None):
+        super().__init__(message)
+        self.request_id = request_id
+
+class AuthenticationError(APIError):
+    """The API key is missing, expired, or invalid.
+
+    Refresh the credential before retrying the request. Repeating the same
+    request with the same invalid credential won't resolve this error.
+    """
+
+class NotFoundError(APIError):
+    """The requested record doesn't exist or isn't visible to the API key."""
+
+class RateLimitError(APIError):
+    """The service rejected a request because its rate limit was reached.
+
+    Wait for `retry_after` seconds before retrying. Add jitter when multiple
+    workers share the same credentials.
+    """
+    def __init__(self, message: str, *, retry_after: float, request_id: str | None = None):
+        super().__init__(message, request_id=request_id)
+        self.retry_after = retry_after

package/examples/code-references/python/orchard/models.py

@@ -0,0 +1,69 @@
+"""Typed request and response models for the records API."""
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import TypedDict
+
+class RecordStatus(str, Enum):
+    """Processing status reported by a record.
+
+    A record moves from `pending` to `ready` after processing completes.
+    Failed records retain their identifier so an application can retry them.
+    """
+    PENDING = "pending"
+    """The record is waiting for processing."""
+    READY = "ready"
+    """The record can be read by applications."""
+    FAILED = "failed"
+    """Processing failed and needs a retry."""
+
+class RecordDict(TypedDict):
+    """Wire representation returned when `Client.fetch(raw=True)` is used."""
+    id: str
+    """Stable record identifier."""
+    title: str
+    """Human-readable record title."""
+    status: str
+    """Processing state encoded as a string."""
+
+@dataclass(frozen=True)
+class RecordInput:
+    """Input used to create a record.
+
+    Provide a title and optional labels. Labels let applications group records
+    without encoding business rules into the record identifier.
+    """
+    title: str
+    """Title to display to readers."""
+    labels: dict[str, str] = field(default_factory=dict)
+    """Application-defined labels, such as `team` or `environment`."""
+
+@dataclass(frozen=True)
+class Record:
+    """A record returned by the service.
+
+    Records are immutable snapshots. Fetch the record again to observe a new
+    processing status rather than changing its fields locally.
+    """
+    id: str
+    """Stable identifier used in fetch and update operations."""
+    title: str
+    """Human-readable title."""
+    status: RecordStatus = RecordStatus.READY
+    """Current processing state."""
+    labels: dict[str, str] = field(default_factory=dict)
+    """Application-defined key/value labels."""
+    created_at: datetime | None = None
+    """Creation time in UTC, if reported by the service."""
+
+    def to_dict(self) -> RecordDict:
+        """Convert a record to its compact wire representation.
+
+        Returns:
+            A mapping with the identifier, title, and string status.
+
+        Examples:
+            >>> Record("rec_42", "Example").to_dict()
+            {'id': 'rec_42', 'title': 'Example', 'status': 'ready'}
+        """
+        return {"id": self.id, "title": self.title, "status": self.status.value}

package/examples/code-references/python/orchard/pagination.py

@@ -0,0 +1,39 @@
+"""Generic containers and cursor helpers for paginated responses."""
+from dataclasses import dataclass
+from typing import Callable, Generic, TypeVar
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+@dataclass(frozen=True)
+class Page(Generic[T]):
+    """One page of results and the cursor needed to continue reading.
+
+    Keep the cursor opaque. Pass it back to `Client.list_records` instead of
+    decoding it or building a cursor from a record identifier.
+    """
+    items: list[T]
+    """Results included in this response."""
+    next_cursor: str | None = None
+    """Continuation cursor, or `None` when this is the final page."""
+    total: int | None = None
+    """Total result count when the service can provide one."""
+
+    @property
+    def has_more(self) -> bool:
+        """Whether another page is available."""
+        return self.next_cursor is not None
+
+    def map(self, transform: Callable[[T], U]) -> "Page[U]":
+        """Transform every item while preserving pagination metadata.
+
+        Args:
+            transform: Function applied once to each item in this page.
+
+        Returns:
+            A new page containing transformed items and the same cursor.
+
+        Examples:
+            >>> page.map(lambda record: record.title)
+        """
+        return Page([transform(item) for item in self.items], self.next_cursor, self.total)