render 1.0.1__py3-none-any.whl

render/__init__.py

@@ -0,0 +1,98 @@
+"""Render Python SDK
+
+Task definition (for workers):
+
+    from render import TaskContext, Workflows
+
+    app = Workflows()
+
+    @app.task
+    def my_task(ctx: TaskContext, x: int) -> int:
+        return x * 2
+
+Synchronous REST API access (default):
+
+    from render import Render
+
+    render = Render()
+
+    result = render.workflows.run_task("my-workflow/my_task", [5])
+
+    task_run = render.workflows.start_task("my-workflow/my_task", [5])
+    # Later: result = render.workflows.get_task_run(task_run.id)
+
+Async REST API access:
+
+    from render import RenderAsync
+
+    render = RenderAsync()
+
+    result = await render.workflows.run_task("my-workflow/my_task", [5])
+
+    task_run = await render.workflows.start_task("my-workflow/my_task", [5])
+    result = await task_run
+"""
+
+__version__ = "1.0.1"
+
+# Render/RenderAsync are lazy-loaded so the workflow worker path stays fast.
+from typing import TYPE_CHECKING
+
+from render.workflows import (
+    Options,
+    Retry,
+    TaskContext,
+    Workflows,
+    start,
+    task,
+)
+
+if TYPE_CHECKING:
+    from render.render import Render
+    from render.render_async import RenderAsync
+
+__all__ = [
+    "__version__",
+    # Primary APIs
+    "Render",  # Sync REST API client (default)
+    "RenderAsync",  # Async REST API client
+    "Workflows",  # Task definition
+    "TaskContext",  # First parameter of every task
+    # Configuration
+    "Options",
+    "Retry",
+    # Deprecated: use Workflows.task and Workflows.start() instead
+    "start",
+    "task",
+]
+
+
+_LAZY_ATTRS = {
+    "Render": ("render.render", "Render"),
+    "RenderAsync": ("render.render_async", "RenderAsync"),
+}
+
+
+def __getattr__(name: str):
+    target = _LAZY_ATTRS.get(name)
+    if target is None:
+        raise AttributeError(f"module 'render' has no attribute {name!r}")
+
+    import importlib
+
+    module_name, attr_name = target
+    value = getattr(importlib.import_module(module_name), attr_name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_LAZY_ATTRS) | set(__all__))
+
+
+# Direct client access available via:
+#   render.client  # Access from existing Render instance
+#   from render.client import Client  # Or import directly
+#
+# Raw API access available via:
+#   from render.public_api import AuthenticatedClient

render/client/__init__.py

@@ -0,0 +1,119 @@
+"""Render REST API Client
+
+A Python client library for interacting with Render's REST API.
+
+Symbols are lazy-loaded so the workflow worker path stays fast — importing
+this package does not pull in the REST client or its models until a caller
+actually references them.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from render.client.client import Client
+    from render.client.types import (
+        CursorParam,
+        LimitParam,
+        ListTaskRunsParams,
+        OwnerIDParam,
+        TaskData,
+        TaskRun,
+        TaskRunDetails,
+        TaskRunStatus,
+        TaskSlug,
+    )
+    from render.client.workflows import WorkflowsService
+    from render.client.workflows_sync import SyncWorkflowsService
+    from render.experimental import (
+        DownloadResponse,
+        ExperimentalService,
+        ObjectApi,
+        ObjectClient,
+        ObjectData,
+        OwnerID,
+        PutObjectResult,
+        Region,
+        ScopedObjectClient,
+        StorageService,
+        SyncExperimentalService,
+        SyncStorageService,
+        UploadResponse,
+    )
+
+__all__ = [
+    "Client",
+    "WorkflowsService",
+    "SyncWorkflowsService",
+    "TaskData",
+    "TaskSlug",
+    "TaskRun",
+    "TaskRunDetails",
+    "TaskRunStatus",
+    "ListTaskRunsParams",
+    "LimitParam",
+    "CursorParam",
+    "OwnerIDParam",
+    # Experimental exports
+    "ExperimentalService",
+    "StorageService",
+    "SyncExperimentalService",
+    "SyncStorageService",
+    "ObjectApi",
+    "ObjectClient",
+    "ScopedObjectClient",
+    "DownloadResponse",
+    "ObjectData",
+    "OwnerID",
+    "PutObjectResult",
+    "Region",
+    "UploadResponse",
+]
+
+
+_LAZY_ATTRS = {
+    "Client": ("render.client.client", "Client"),
+    "WorkflowsService": ("render.client.workflows", "WorkflowsService"),
+    "SyncWorkflowsService": (
+        "render.client.workflows_sync",
+        "SyncWorkflowsService",
+    ),
+    "TaskData": ("render.client.types", "TaskData"),
+    "TaskSlug": ("render.client.types", "TaskSlug"),
+    "TaskRun": ("render.client.types", "TaskRun"),
+    "TaskRunDetails": ("render.client.types", "TaskRunDetails"),
+    "TaskRunStatus": ("render.client.types", "TaskRunStatus"),
+    "ListTaskRunsParams": ("render.client.types", "ListTaskRunsParams"),
+    "LimitParam": ("render.client.types", "LimitParam"),
+    "CursorParam": ("render.client.types", "CursorParam"),
+    "OwnerIDParam": ("render.client.types", "OwnerIDParam"),
+    "ExperimentalService": ("render.experimental", "ExperimentalService"),
+    "StorageService": ("render.experimental", "StorageService"),
+    "SyncExperimentalService": ("render.experimental", "SyncExperimentalService"),
+    "SyncStorageService": ("render.experimental", "SyncStorageService"),
+    "ObjectApi": ("render.experimental", "ObjectApi"),
+    "ObjectClient": ("render.experimental", "ObjectClient"),
+    "ScopedObjectClient": ("render.experimental", "ScopedObjectClient"),
+    "DownloadResponse": ("render.experimental", "DownloadResponse"),
+    "ObjectData": ("render.experimental", "ObjectData"),
+    "OwnerID": ("render.experimental", "OwnerID"),
+    "PutObjectResult": ("render.experimental", "PutObjectResult"),
+    "Region": ("render.experimental", "Region"),
+    "UploadResponse": ("render.experimental", "UploadResponse"),
+}
+
+
+def __getattr__(name: str):
+    target = _LAZY_ATTRS.get(name)
+    if target is None:
+        raise AttributeError(f"module 'render.client' has no attribute {name!r}")
+
+    import importlib
+
+    module_name, attr_name = target
+    value = getattr(importlib.import_module(module_name), attr_name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_LAZY_ATTRS) | set(__all__))

render/client/client.py

@@ -0,0 +1,110 @@
+"""Render API Client
+
+This module provides the main Client class for interacting with Render's REST API.
+"""
+
+import os
+
+from render.client.workflows import WorkflowsService
+from render.experimental.experimental import ExperimentalService
+from render.public_api.client import AuthenticatedClient
+from render.public_api.client import Client as PublicApiClient
+from render.version import get_user_agent
+
+
+class Client:
+    """Render API client
+
+    This class provides access to Render's REST API with automatic authentication
+    and service-specific clients.
+
+    Attributes:
+        internal: The internal generated API client
+        token: The authentication token
+        base_url: The API base URL
+        workflows: Service client for workflow operations
+        experimental: Service client for experimental features
+    """
+
+    token: str
+
+    def __init__(
+        self,
+        token: str | None = None,
+        base_url: str = "https://api.render.com",
+        owner_id: str | None = None,
+        region: str | None = None,
+    ):
+        """Initialize a new Render API client.
+
+        Args:
+            token: API authentication token. If not provided, will look for
+                  RENDER_API_KEY environment variable.
+            owner_id: Default owner ID for object storage. If not provided,
+                     will look for RENDER_WORKSPACE_ID environment variable.
+            region: Default region for object storage. If not provided,
+                   will look for RENDER_REGION environment variable.
+            *options: Client configuration options
+        """
+        # Use the local dev URL when provided,
+        # Otherwise if local dev is enabled, use the default local dev URL
+        # Otherwise, use the base URL
+        use_local_dev = os.getenv("RENDER_USE_LOCAL_DEV", "")
+        local_dev_url = os.getenv("RENDER_LOCAL_DEV_URL", "")
+        is_local_dev = bool(local_dev_url) or use_local_dev in [
+            "1",
+            "t",
+            "T",
+            "true",
+            "TRUE",
+            "True",
+        ]
+
+        # Set default values
+        if token is None:
+            self.token = os.getenv("RENDER_API_KEY", "")
+            if self.token == "" and not is_local_dev:
+                raise ValueError(
+                    "Either provide a token or set the RENDER_API_KEY "
+                    + "environment variable"
+                )
+        else:
+            self.token = token
+
+        workspace_id = os.getenv("RENDER_WORKSPACE_ID", "") or None
+        self.owner_id: str | None = owner_id or workspace_id
+        self.region: str | None = region or os.getenv("RENDER_REGION", "") or None
+
+        if local_dev_url:
+            self.base_url = local_dev_url
+        elif is_local_dev:
+            self.base_url = "http://localhost:8120"
+        else:
+            self.base_url = base_url
+
+        # Ensure base URL has proper format
+        if not self.base_url.startswith(("http://", "https://")):
+            self.base_url = f"https://{self.base_url}"
+
+        # Remove trailing slash and add /v1
+        api_base = f"{self.base_url.rstrip('/')}/v1"
+
+        # Create the internal API client. When running against local dev without a
+        # token, fall back to an unauthenticated client so we don't emit an
+        # invalid "Authorization: Bearer " header.
+        self.internal: AuthenticatedClient | PublicApiClient
+        if self.token:
+            self.internal = AuthenticatedClient(
+                base_url=api_base,
+                token=self.token,
+                headers={"User-Agent": get_user_agent()},
+            )
+        else:
+            self.internal = PublicApiClient(
+                base_url=api_base,
+                headers={"User-Agent": get_user_agent()},
+            )
+
+        # Initialize service clients
+        self.workflows = WorkflowsService(self)
+        self.experimental = ExperimentalService(self)

render/client/errors.py

@@ -0,0 +1,39 @@
+class RenderError(Exception):
+    """Base exception for all Render errors."""
+
+    pass
+
+
+class ClientError(RenderError):
+    """Exception for client errors. This is returned when
+    the client makes a request to the API and the API returns a 4xx error."""
+
+    pass
+
+
+class RateLimitError(ClientError):
+    """Exception for rate limit errors. This is returned when
+    the client makes a request to the API and the API returns a 429 error."""
+
+    pass
+
+
+class TimeoutError(RenderError):
+    """Exception for timeout errors. This is returned when the
+    client makes a request to the API and the request times out."""
+
+    pass
+
+
+class ServerError(RenderError):
+    """Exception for server errors. This is returned when the
+    client makes a request to the API and the API returns a 5xx error."""
+
+    pass
+
+
+class TaskRunError(RenderError):
+    """Exception for task run errors. This is returned when a running
+    task fails."""
+
+    pass

render/client/sse.py

@@ -0,0 +1,90 @@
+"""Server-Sent Events (SSE) utilities
+
+This module provides SSE stream parsing functionality for task run events.
+"""
+
+import json
+import logging
+from collections.abc import AsyncIterator
+from typing import Any
+
+from render.client.types import TaskRunDetails
+
+logger = logging.getLogger(__name__)
+
+
+class SSEParser:
+    """Stateful parser for Server-Sent Events byte streams.
+
+    Accepts raw byte chunks via feed() and returns any complete
+    TaskRunDetails events parsed from the stream. Shared by both
+    the async and sync parse_stream entry points.
+    """
+
+    def __init__(self) -> None:
+        self._buffer = ""
+        self._event_data: dict[str, Any] = {}
+
+    def feed(self, chunk: bytes) -> list[TaskRunDetails]:
+        """Feed a chunk of bytes and return any completed events."""
+        results: list[TaskRunDetails] = []
+        self._buffer += chunk.decode("utf-8", errors="ignore")
+
+        while "\n" in self._buffer:
+            line, self._buffer = self._buffer.split("\n", 1)
+            line = line.rstrip("\r")
+
+            # Empty line indicates end of event
+            if not line:
+                if "data" in self._event_data and "event" in self._event_data:
+                    try:
+                        # NOTE: right now, the API emits all terminal events as
+                        # "task.completed" events regardless of status. The true
+                        # event status is contained elsewhere in the event data.
+                        # These are here for forward compatibility.
+                        if self._event_data["event"] in (
+                            "task.canceled",
+                            "task.completed",
+                            "task.failed",
+                            "task.succeeded",
+                        ):
+                            data = json.loads(self._event_data["data"])
+                            results.append(_convert_to_task_run_details(data))
+                    except Exception as e:
+                        logger.error(f"Error parsing event: {e}")
+
+                self._event_data = {}
+                continue
+
+            # Parse SSE fields
+            if ":" in line:
+                field, value = line.split(":", 1)
+                self._event_data[field.strip()] = value.strip()
+
+        return results
+
+
+async def parse_stream(
+    bytes_iter: AsyncIterator[bytes],
+) -> AsyncIterator[TaskRunDetails]:
+    """Parse an async stream of bytes into TaskRunDetails."""
+    parser = SSEParser()
+    async for chunk in bytes_iter:
+        for event in parser.feed(chunk):
+            yield event
+
+
+def _convert_to_task_run_details(data: dict) -> TaskRunDetails:
+    """Convert JSON event data to TaskRunDetails object.
+
+    Args:
+        data: Raw JSON event data
+
+    Returns:
+        TaskRunDetails: Converted task run details
+
+    Raises:
+        KeyError: If required fields are missing
+        TypeError: If data types are incorrect
+    """
+    return TaskRunDetails.from_dict(data)

render/client/sse_sync.py

@@ -0,0 +1,20 @@
+"""Synchronous Server-Sent Events (SSE) utilities.
+
+Sync entry point for SSE stream parsing. All parsing logic lives
+in SSEParser (defined in sse.py); this module only provides the
+sync iteration wrapper.
+"""
+
+from collections.abc import Iterator
+
+from render.client.sse import SSEParser
+from render.client.types import TaskRunDetails
+
+
+def parse_stream(
+    bytes_iter: Iterator[bytes],
+) -> Iterator[TaskRunDetails]:
+    """Parse a sync stream of bytes into TaskRunDetails."""
+    parser = SSEParser()
+    for chunk in bytes_iter:
+        yield from parser.feed(chunk)