render 1.0.1__py3-none-any.whl

render/experimental/key_value/types.py

@@ -0,0 +1,130 @@
+"""Type definitions for Key Value experimental feature."""
+
+from dataclasses import dataclass
+from typing import Literal
+
+from render.public_api.models.cidr_block_and_description import (
+    CidrBlockAndDescription,
+)
+from render.public_api.models.database_status import DatabaseStatus
+from render.public_api.models.key_value_plan import KeyValuePlan
+from render.public_api.models.maxmemory_policy import MaxmemoryPolicy
+
+__all__ = [
+    "ConnectionInfo",
+    "InstanceConfiguration",
+    "IPAllowListEntry",
+    "KeyValueInstance",
+    "MaxmemoryPolicy",
+    "NameOwnerIdOptions",
+    "Options",
+    "OwnerId",
+    "Plan",
+    "ServiceIdOptions",
+]
+
+# Excludes "custom", which is a managed plan not available for provisioning
+Plan = Literal[
+    "free",
+    "starter",
+    "standard",
+    "pro",
+    "pro_plus",
+]
+
+# Owner ID (format: "tea-xxx" for workspace teams, "own-xxx" for individuals)
+OwnerId = str
+
+# IP allow list entry is a CIDR block paired with a description
+IPAllowListEntry = CidrBlockAndDescription
+
+
+@dataclass
+class KeyValueInstance:
+    """Subset of Key Value instance state needed by the client.
+
+    Returned by all KeyValueApi methods so that client.py and compare.py
+    don't depend on the generated KeyValue / KeyValueDetail models directly.
+
+    Attributes:
+        id: The Render service ID of the instance.
+        status: Current lifecycle status.
+        plan: Current billing plan.
+        maxmemory_policy: Current eviction policy, or None if unset.
+        ip_allow_list: Current IP allow list entries.
+    """
+
+    id: str
+    status: DatabaseStatus
+    plan: KeyValuePlan
+    maxmemory_policy: MaxmemoryPolicy | None
+    ip_allow_list: list[IPAllowListEntry]
+
+
+@dataclass
+class ConnectionInfo:
+    """Parsed connection information for a Key Value instance.
+
+    Attributes:
+        host: Hostname of the Key Value instance.
+        port: Port number.
+        username: Optional username for authentication.
+        password: Optional password for authentication.
+    """
+
+    host: str
+    port: int
+    username: str | None = None
+    password: str | None = None
+
+
+@dataclass
+class InstanceConfiguration:
+    """Configuration settings for an instance, used for automatic provisioning
+    and settings sync
+
+    Attributes:
+        plan: Desired plan
+        maxmemory_policy: Desired eviction policy
+        ip_allow_list: Desired IP allowlist for external connections
+    """
+
+    plan: Plan | None = None
+    maxmemory_policy: MaxmemoryPolicy | None = None
+    ip_allow_list: list[IPAllowListEntry] | None = None
+
+
+@dataclass
+class ServiceIdOptions:
+    """Options for identifying a Key Value instance by its Render service ID.
+
+    Attributes:
+        service_id: The Render service ID of the Key Value instance.
+        auto_provision: Instance configuration settings to use for automatic
+            provisioning and settings sync. Set to `False` to disable
+            automatic instance changes
+    """
+
+    service_id: str
+    auto_provision: bool | InstanceConfiguration | None = None
+
+
+@dataclass
+class NameOwnerIdOptions:
+    """Options for identifying a Key Value instance by name.
+
+    Attributes:
+        name: Name of the Key Value instance.
+        owner_id: Owner ID of the instance. Must be set here, when initializing the
+            Render client, or via the RENDER_WORKSPACE_ID environment variable.
+        auto_provision: Instance configuration settings to use for automatic
+            provisioning and settings sync. Set to `False` to disable
+            automatic instance changes
+    """
+
+    name: str
+    owner_id: OwnerId | None = None
+    auto_provision: bool | InstanceConfiguration | None = None
+
+
+Options = ServiceIdOptions | NameOwnerIdOptions

render/experimental/key_value/utils.py

@@ -0,0 +1,11 @@
+"""Shared utilities for the Key Value module."""
+
+import os
+
+
+def _format_error_message(failure: str, call_to_action: str) -> str:
+    return f"{failure}\n\n{call_to_action}"
+
+
+def _is_local_dev() -> bool:
+    return os.environ.get("RENDER_USE_LOCAL_DEV") == "true"

render/experimental/object/__init__.py

@@ -0,0 +1,38 @@
+"""Object storage API exports."""
+
+from render.experimental.object.api import ObjectApi
+from render.experimental.object.api_sync import SyncObjectApi
+from render.experimental.object.client import ObjectClient, ScopedObjectClient
+from render.experimental.object.client_sync import (
+    SyncObjectClient,
+    SyncScopedObjectClient,
+)
+from render.experimental.object.types import (
+    DownloadResponse,
+    ListObjectsResponse,
+    ObjectData,
+    ObjectMetadata,
+    OwnerID,
+    PutObjectResult,
+    Region,
+    UploadResponse,
+)
+
+__all__ = [
+    # API classes
+    "ObjectApi",
+    "ObjectClient",
+    "ScopedObjectClient",
+    "SyncObjectApi",
+    "SyncObjectClient",
+    "SyncScopedObjectClient",
+    # Types
+    "DownloadResponse",
+    "ListObjectsResponse",
+    "ObjectData",
+    "ObjectMetadata",
+    "OwnerID",
+    "PutObjectResult",
+    "Region",
+    "UploadResponse",
+]

render/experimental/object/api.py

@@ -0,0 +1,250 @@
+"""Typed Object API Client
+
+Provides idiomatic Python wrapper around the raw OpenAPI client.
+Handles presigned URL flow but still exposes the two-step nature
+(get URL, then upload/download). Useful for advanced use cases
+requiring fine-grained control.
+"""
+
+from typing import TYPE_CHECKING, cast
+
+from render.client.errors import RenderError
+from render.client.util import handle_http_errors
+from render.experimental.object.types import (
+    DownloadResponse,
+    ListObjectsResponse,
+    ObjectMetadata,
+    UploadResponse,
+)
+from render.public_api.api.object_storage import (
+    delete_object,
+    get_object,
+    list_objects,
+    put_object,
+)
+from render.public_api.models.error import Error
+from render.public_api.models.get_object_output import GetObjectOutput
+from render.public_api.models.list_objects_response import (
+    ListObjectsResponse as GeneratedListObjectsResponse,
+)
+from render.public_api.models.put_object_input import (
+    PutObjectInput as PutObjectInputModel,
+)
+from render.public_api.models.put_object_output import PutObjectOutput
+from render.public_api.models.region import Region
+from render.public_api.types import UNSET, Response
+
+if TYPE_CHECKING:
+    from render.public_api.client import AuthenticatedClient, Client
+
+
+class ObjectApi:
+    """Typed Object API Client
+
+    Provides idiomatic Python wrapper around the raw OpenAPI client.
+    Handles presigned URL flow but still exposes the two-step nature.
+    """
+
+    def __init__(self, client: "AuthenticatedClient | Client"):
+        self.client = client
+
+    async def get_upload_url(
+        self,
+        owner_id: str,
+        region: Region | str,
+        key: str,
+        size_bytes: int,
+    ) -> UploadResponse:
+        """Get a presigned URL for uploading an object.
+
+        Args:
+            owner_id: Owner ID (workspace team ID)
+            region: Storage region
+            key: Object key (path)
+            size_bytes: Size of the object in bytes
+
+        Returns:
+            UploadResponse: Upload URL with expiration and size limit
+
+        Raises:
+            ClientError: For 4xx client errors
+            ServerError: For 5xx server errors
+            TimeoutError: If the request times out
+        """
+        response = await self._get_upload_url_api_call(
+            owner_id, region, key, size_bytes
+        )
+
+        if not isinstance(response.parsed, PutObjectOutput):
+            raise RenderError("Failed to get upload URL: unexpected response type")
+
+        return UploadResponse(
+            url=response.parsed.url,
+            expires_at=response.parsed.expires_at,
+            max_size_bytes=response.parsed.max_size_bytes,
+        )
+
+    @handle_http_errors("get upload URL")
+    async def _get_upload_url_api_call(
+        self,
+        owner_id: str,
+        region: Region | str,
+        key: str,
+        size_bytes: int,
+    ) -> Response[Error | PutObjectOutput]:
+        """Internal method to make the get upload URL API call."""
+        body = PutObjectInputModel(size_bytes=size_bytes)
+
+        return await put_object.asyncio_detailed(
+            owner_id=owner_id,
+            region=cast(Region, region),
+            key=key,
+            client=self.client,
+            body=body,
+        )
+
+    async def get_download_url(
+        self,
+        owner_id: str,
+        region: Region | str,
+        key: str,
+    ) -> DownloadResponse:
+        """Get a presigned URL for downloading an object.
+
+        Args:
+            owner_id: Owner ID (workspace team ID)
+            region: Storage region
+            key: Object key (path)
+
+        Returns:
+            DownloadResponse: Download URL with expiration
+
+        Raises:
+            ClientError: For 4xx client errors
+            ServerError: For 5xx server errors
+            TimeoutError: If the request times out
+        """
+        response = await self._get_download_url_api_call(owner_id, region, key)
+
+        if not isinstance(response.parsed, GetObjectOutput):
+            raise RenderError("Failed to get download URL: unexpected response type")
+
+        return DownloadResponse(
+            url=response.parsed.url,
+            expires_at=response.parsed.expires_at,
+        )
+
+    @handle_http_errors("get download URL")
+    async def _get_download_url_api_call(
+        self,
+        owner_id: str,
+        region: Region | str,
+        key: str,
+    ) -> Response[Error | GetObjectOutput]:
+        """Internal method to make the get download URL API call."""
+        return await get_object.asyncio_detailed(
+            owner_id=owner_id,
+            region=cast(Region, region),
+            key=key,
+            client=self.client,
+        )
+
+    async def delete(
+        self,
+        owner_id: str,
+        region: Region | str,
+        key: str,
+    ) -> None:
+        """Delete an object.
+
+        Args:
+            owner_id: Owner ID (workspace team ID)
+            region: Storage region
+            key: Object key (path)
+
+        Raises:
+            ClientError: For 4xx client errors
+            ServerError: For 5xx server errors
+            TimeoutError: If the request times out
+        """
+        await self._delete_api_call(owner_id, region, key)
+
+    @handle_http_errors("delete object")
+    async def _delete_api_call(
+        self,
+        owner_id: str,
+        region: Region | str,
+        key: str,
+    ) -> Response[Error | None]:
+        """Internal method to make the delete object API call."""
+        return await delete_object.asyncio_detailed(
+            owner_id=owner_id,
+            region=cast(Region, region),
+            key=key,
+            client=self.client,
+        )
+
+    async def list_objects(
+        self,
+        owner_id: str,
+        region: Region | str,
+        cursor: str | None = None,
+        limit: int | None = None,
+    ) -> ListObjectsResponse:
+        """List objects in storage.
+
+        Args:
+            owner_id: Owner ID (workspace team ID)
+            region: Storage region
+            cursor: Pagination cursor from previous response
+            limit: Maximum number of objects to return (default 20)
+
+        Returns:
+            ListObjectsResponse: List of object metadata with optional next cursor
+
+        Raises:
+            ClientError: For 4xx client errors
+            ServerError: For 5xx server errors
+            TimeoutError: If the request times out
+        """
+        response = await self._list_objects_api_call(owner_id, region, cursor, limit)
+
+        if not isinstance(response.parsed, GeneratedListObjectsResponse):
+            raise RenderError("Failed to list objects: unexpected response type")
+
+        parsed = response.parsed
+        objects = [
+            ObjectMetadata(
+                key=item.object_.key,
+                size=item.object_.size_bytes,
+                last_modified=item.object_.last_modified,
+            )
+            for item in parsed.items
+        ]
+
+        next_cursor = (
+            parsed.next_cursor if isinstance(parsed.next_cursor, str) else None
+        )
+
+        return ListObjectsResponse(
+            objects=objects,
+            has_next=parsed.has_next,
+            next_cursor=next_cursor,
+        )
+
+    @handle_http_errors("list objects")
+    async def _list_objects_api_call(
+        self,
+        owner_id: str,
+        region: Region | str,
+        cursor: str | None,
+        limit: int | None,
+    ) -> Response[Error | GeneratedListObjectsResponse]:
+        """Internal method to make the list objects API call."""
+        return await list_objects.asyncio_detailed(
+            owner_id=owner_id,
+            region=cast(Region, region),
+            cursor=cursor if cursor is not None else UNSET,
+            limit=limit if limit is not None else UNSET,
+            client=self.client,
+        )

render/experimental/object/api_sync.py

@@ -0,0 +1,250 @@
+# Auto-generated sync version. Do not edit — run scripts/unasync.py instead.
+
+"""Typed Object API Client
+
+Provides idiomatic Python wrapper around the raw OpenAPI client.
+Handles presigned URL flow but still exposes the two-step nature
+(get URL, then upload/download). Useful for advanced use cases
+requiring fine-grained control.
+"""
+
+from typing import TYPE_CHECKING, cast
+
+from render.client.errors import RenderError
+from render.client.util_sync import handle_http_errors
+from render.experimental.object.types import (
+    DownloadResponse,
+    ListObjectsResponse,
+    ObjectMetadata,
+    UploadResponse,
+)
+from render.public_api.api.object_storage import (
+    delete_object,
+    get_object,
+    list_objects,
+    put_object,
+)
+from render.public_api.models.error import Error
+from render.public_api.models.get_object_output import GetObjectOutput
+from render.public_api.models.list_objects_response import (
+    ListObjectsResponse as GeneratedListObjectsResponse,
+)
+from render.public_api.models.put_object_input import (
+    PutObjectInput as PutObjectInputModel,
+)
+from render.public_api.models.put_object_output import PutObjectOutput
+from render.public_api.models.region import Region
+from render.public_api.types import UNSET, Response
+
+if TYPE_CHECKING:
+    from render.public_api.client import AuthenticatedClient, Client
+
+
+class SyncObjectApi:
+    """Typed Object API Client
+
+    Provides idiomatic Python wrapper around the raw OpenAPI client.
+    Handles presigned URL flow but still exposes the two-step nature.
+    """
+
+    def __init__(self, client: "AuthenticatedClient | Client"):
+        self.client = client
+
+    def get_upload_url(
+        self,
+        owner_id: str,
+        region: Region | str,
+        key: str,
+        size_bytes: int,
+    ) -> UploadResponse:
+        """Get a presigned URL for uploading an object.
+
+        Args:
+            owner_id: Owner ID (workspace team ID)
+            region: Storage region
+            key: Object key (path)
+            size_bytes: Size of the object in bytes
+
+        Returns:
+            UploadResponse: Upload URL with expiration and size limit
+
+        Raises:
+            ClientError: For 4xx client errors
+            ServerError: For 5xx server errors
+            TimeoutError: If the request times out
+        """
+        response = self._get_upload_url_api_call(owner_id, region, key, size_bytes)
+
+        if not isinstance(response.parsed, PutObjectOutput):
+            raise RenderError("Failed to get upload URL: unexpected response type")
+
+        return UploadResponse(
+            url=response.parsed.url,
+            expires_at=response.parsed.expires_at,
+            max_size_bytes=response.parsed.max_size_bytes,
+        )
+
+    @handle_http_errors("get upload URL")
+    def _get_upload_url_api_call(
+        self,
+        owner_id: str,
+        region: Region | str,
+        key: str,
+        size_bytes: int,
+    ) -> Response[Error | PutObjectOutput]:
+        """Internal method to make the get upload URL API call."""
+        body = PutObjectInputModel(size_bytes=size_bytes)
+
+        return put_object.sync_detailed(
+            owner_id=owner_id,
+            region=cast(Region, region),
+            key=key,
+            client=self.client,
+            body=body,
+        )
+
+    def get_download_url(
+        self,
+        owner_id: str,
+        region: Region | str,
+        key: str,
+    ) -> DownloadResponse:
+        """Get a presigned URL for downloading an object.
+
+        Args:
+            owner_id: Owner ID (workspace team ID)
+            region: Storage region
+            key: Object key (path)
+
+        Returns:
+            DownloadResponse: Download URL with expiration
+
+        Raises:
+            ClientError: For 4xx client errors
+            ServerError: For 5xx server errors
+            TimeoutError: If the request times out
+        """
+        response = self._get_download_url_api_call(owner_id, region, key)
+
+        if not isinstance(response.parsed, GetObjectOutput):
+            raise RenderError("Failed to get download URL: unexpected response type")
+
+        return DownloadResponse(
+            url=response.parsed.url,
+            expires_at=response.parsed.expires_at,
+        )
+
+    @handle_http_errors("get download URL")
+    def _get_download_url_api_call(
+        self,
+        owner_id: str,
+        region: Region | str,
+        key: str,
+    ) -> Response[Error | GetObjectOutput]:
+        """Internal method to make the get download URL API call."""
+        return get_object.sync_detailed(
+            owner_id=owner_id,
+            region=cast(Region, region),
+            key=key,
+            client=self.client,
+        )
+
+    def delete(
+        self,
+        owner_id: str,
+        region: Region | str,
+        key: str,
+    ) -> None:
+        """Delete an object.
+
+        Args:
+            owner_id: Owner ID (workspace team ID)
+            region: Storage region
+            key: Object key (path)
+
+        Raises:
+            ClientError: For 4xx client errors
+            ServerError: For 5xx server errors
+            TimeoutError: If the request times out
+        """
+        self._delete_api_call(owner_id, region, key)
+
+    @handle_http_errors("delete object")
+    def _delete_api_call(
+        self,
+        owner_id: str,
+        region: Region | str,
+        key: str,
+    ) -> Response[Error | None]:
+        """Internal method to make the delete object API call."""
+        return delete_object.sync_detailed(
+            owner_id=owner_id,
+            region=cast(Region, region),
+            key=key,
+            client=self.client,
+        )
+
+    def list_objects(
+        self,
+        owner_id: str,
+        region: Region | str,
+        cursor: str | None = None,
+        limit: int | None = None,
+    ) -> ListObjectsResponse:
+        """List objects in storage.
+
+        Args:
+            owner_id: Owner ID (workspace team ID)
+            region: Storage region
+            cursor: Pagination cursor from previous response
+            limit: Maximum number of objects to return (default 20)
+
+        Returns:
+            ListObjectsResponse: List of object metadata with optional next cursor
+
+        Raises:
+            ClientError: For 4xx client errors
+            ServerError: For 5xx server errors
+            TimeoutError: If the request times out
+        """
+        response = self._list_objects_api_call(owner_id, region, cursor, limit)
+
+        if not isinstance(response.parsed, GeneratedListObjectsResponse):
+            raise RenderError("Failed to list objects: unexpected response type")
+
+        parsed = response.parsed
+        objects = [
+            ObjectMetadata(
+                key=item.object_.key,
+                size=item.object_.size_bytes,
+                last_modified=item.object_.last_modified,
+            )
+            for item in parsed.items
+        ]
+
+        next_cursor = (
+            parsed.next_cursor if isinstance(parsed.next_cursor, str) else None
+        )
+
+        return ListObjectsResponse(
+            objects=objects,
+            has_next=parsed.has_next,
+            next_cursor=next_cursor,
+        )
+
+    @handle_http_errors("list objects")
+    def _list_objects_api_call(
+        self,
+        owner_id: str,
+        region: Region | str,
+        cursor: str | None,
+        limit: int | None,
+    ) -> Response[Error | GeneratedListObjectsResponse]:
+        """Internal method to make the list objects API call."""
+        return list_objects.sync_detailed(
+            owner_id=owner_id,
+            region=cast(Region, region),
+            cursor=cursor if cursor is not None else UNSET,
+            limit=limit if limit is not None else UNSET,
+            client=self.client,
+        )