render 1.0.1__py3-none-any.whl

render/experimental/experimental.py

@@ -0,0 +1,93 @@
+"""Experimental Service
+
+This module provides the ExperimentalService class that exposes experimental features
+from the Render SDK.
+"""
+
+from typing import TYPE_CHECKING
+
+from render.experimental.key_value.api import KeyValueApi
+from render.experimental.key_value.provider import KeyValueProvider
+from render.experimental.object.client import ObjectClient
+from render.experimental.sandbox.client import SandboxClient
+
+if TYPE_CHECKING:
+    from render.client.client import Client
+
+
+class StorageService:
+    """Storage Service
+
+    Provides access to experimental storage features.
+
+    Example:
+        ```python
+        # Access object storage
+        await client.experimental.storage.objects.put(
+            owner_id="tea-xxxxx",
+            region="oregon",
+            key="file.png",
+            data=b"content"
+        )
+        ```
+    """
+
+    def __init__(self, client: "Client"):
+        """Initialize the storage service.
+
+        Args:
+            client: The Render client instance
+        """
+        self.objects = ObjectClient(
+            client.internal,
+            default_owner_id=client.owner_id,
+            default_region=client.region,
+        )
+
+
+class ExperimentalService:
+    """Experimental Service
+
+    Provides access to experimental Render SDK features.
+
+    Features in this namespace may change or be removed without a migration plan.
+    When a feature stabilizes, it will be promoted to the main SDK namespace.
+
+    Example:
+        ```python
+        from render import RenderAsync
+
+        render = RenderAsync()
+
+        # Access experimental object storage
+        await render.experimental.storage.objects.put(
+            owner_id="tea-xxxxx",
+            region="oregon",
+            key="file.png",
+            data=b"content"
+        )
+
+        # Access experimental Key Value support
+        from render.experimental.key_value import NameOwnerIdOptions
+        redis = await render.experimental.key_value.new_client(
+            NameOwnerIdOptions(name="my-cache")
+        )
+        ```
+    """
+
+    def __init__(self, client: "Client"):
+        """Initialize the experimental service.
+
+        Args:
+            client: The Render client instance
+        """
+        self.storage = StorageService(client)
+        self.key_value = KeyValueProvider(
+            KeyValueApi(client.internal),
+            default_owner_id=client.owner_id,
+        )
+        self.sandboxes = SandboxClient(
+            client.internal,
+            default_owner_id=client.owner_id,
+            default_region=client.region,
+        )

render/experimental/experimental_sync.py

@@ -0,0 +1,78 @@
+"""Synchronous Experimental Service.
+
+This module provides the sync versions of ExperimentalService and StorageService.
+"""
+
+from typing import TYPE_CHECKING
+
+from render.experimental.object.client_sync import SyncObjectClient
+from render.experimental.sandbox.client_sync import SyncSandboxClient
+
+if TYPE_CHECKING:
+    from render.client.client import Client
+
+
+class SyncStorageService:
+    """Synchronous Storage Service.
+
+    Provides access to experimental storage features using synchronous HTTP calls.
+
+    Example:
+        ```python
+        client.experimental.storage.objects.put(
+            owner_id="tea-xxxxx",
+            region="oregon",
+            key="file.png",
+            data=b"content"
+        )
+        ```
+    """
+
+    def __init__(self, client: "Client"):
+        """Initialize the storage service.
+
+        Args:
+            client: The Render client instance
+        """
+        self.objects = SyncObjectClient(
+            client.internal,
+            default_owner_id=client.owner_id,
+            default_region=client.region,
+        )
+
+
+class SyncExperimentalService:
+    """Synchronous Experimental Service.
+
+    Provides access to experimental Render SDK features using synchronous HTTP calls.
+
+    Features in this namespace may change or be removed without a migration plan.
+    When a feature stabilizes, it will be promoted to the main SDK namespace.
+
+    Example:
+        ```python
+        from render import Render
+
+        render = Render()
+
+        render.experimental.storage.objects.put(
+            owner_id="tea-xxxxx",
+            region="oregon",
+            key="file.png",
+            data=b"content"
+        )
+        ```
+    """
+
+    def __init__(self, client: "Client"):
+        """Initialize the experimental service.
+
+        Args:
+            client: The Render client instance
+        """
+        self.storage = SyncStorageService(client)
+        self.sandboxes = SyncSandboxClient(
+            client.internal,
+            default_owner_id=client.owner_id,
+            default_region=client.region,
+        )

render/experimental/key_value/__init__.py

@@ -0,0 +1,33 @@
+"""Key Value experimental feature."""
+
+from render.experimental.key_value.api import KeyValueApi
+from render.experimental.key_value.provider import KeyValueProvider
+from render.experimental.key_value.types import (
+    ConnectionInfo,
+    InstanceConfiguration,
+    IPAllowListEntry,
+    MaxmemoryPolicy,
+    NameOwnerIdOptions,
+    Options,
+    OwnerId,
+    Plan,
+    ServiceIdOptions,
+)
+
+__all__ = [
+    # Classes
+    "KeyValueApi",
+    "KeyValueProvider",
+    # Options types
+    "InstanceConfiguration",
+    "NameOwnerIdOptions",
+    "Options",
+    "ServiceIdOptions",
+    # Value types
+    "ConnectionInfo",
+    "IPAllowListEntry",
+    # Type aliases
+    "MaxmemoryPolicy",
+    "OwnerId",
+    "Plan",
+]

render/experimental/key_value/api.py

@@ -0,0 +1,243 @@
+"""Layer 2 API client tailored to Key Value use-cases."""
+
+import os
+from http import HTTPStatus
+
+from render.client.errors import ClientError, ServerError
+from render.public_api.api.key_value import (
+    create_key_value,
+    list_key_value,
+    retrieve_key_value,
+    retrieve_key_value_connection_info,
+    update_key_value,
+)
+from render.public_api.client import AuthenticatedClient, Client
+from render.public_api.models.key_value import KeyValue
+from render.public_api.models.key_value_connection_info import (
+    KeyValueConnectionInfo,
+)
+from render.public_api.models.key_value_detail import KeyValueDetail
+from render.public_api.models.key_value_patch_input import KeyValuePATCHInput
+from render.public_api.models.key_value_post_input import KeyValuePOSTInput
+from render.public_api.models.maxmemory_policy import MaxmemoryPolicy
+from render.public_api.types import Unset
+
+from .types import KeyValueInstance
+from .utils import _format_error_message
+
+
+def _is_render() -> bool:
+    return os.environ.get("RENDER") == "true"
+
+
+def _unauthorized_error() -> ClientError:
+    return ClientError(
+        _format_error_message(
+            "The provided Render API Token is not authorized.",
+            "Please double-check the token is correct.",
+        )
+    )
+
+
+def _unexpected_error(operation: str, status_code: int) -> ClientError | ServerError:
+    message = f"Unexpected error while {operation}"
+    if status_code >= HTTPStatus.INTERNAL_SERVER_ERROR:
+        return ServerError(message)
+    return ClientError(message)
+
+
+def _to_instance(detail: KeyValue | KeyValueDetail) -> KeyValueInstance:
+    maxmemory_policy = detail.options.maxmemory_policy
+    return KeyValueInstance(
+        id=detail.id,
+        status=detail.status,
+        plan=detail.plan,
+        maxmemory_policy=(
+            None
+            if isinstance(maxmemory_policy, Unset)
+            else MaxmemoryPolicy(maxmemory_policy)
+        ),
+        ip_allow_list=list(detail.ip_allow_list),
+    )
+
+
+class KeyValueApi:
+    """Layer 2 Key Value API client.
+
+    Wraps the generated OpenAPI operations with typed return values and
+    explicit error messages for common failure cases (401, 404).
+    For most use cases, prefer :class:`KeyValueClient`.
+    """
+
+    def __init__(self, client: "AuthenticatedClient | Client"):
+        self.client = client
+
+    async def find_by_id(self, key_value_id: str) -> KeyValueInstance:
+        """Look up a Key Value instance by its service ID.
+
+        Args:
+            key_value_id: The Render service ID of the Key Value instance.
+
+        Returns:
+            KeyValueInstance: Instance state.
+
+        Raises:
+            ClientError: If the ID is not found or the API token is unauthorized.
+            ServerError: For 5xx server errors.
+        """
+        response = await retrieve_key_value.asyncio_detailed(
+            redis_id=key_value_id,
+            client=self.client,
+        )
+
+        if response.status_code == HTTPStatus.UNAUTHORIZED:
+            raise _unauthorized_error()
+
+        if response.status_code == HTTPStatus.NOT_FOUND:
+            raise ClientError(
+                _format_error_message(
+                    f"Unable to locate a Key Value with ID {key_value_id}",
+                    "Please double-check the ID is correct",
+                )
+            )
+
+        if not isinstance(response.parsed, KeyValueDetail):
+            raise _unexpected_error(
+                f"fetching info about Key Value {key_value_id}",
+                response.status_code,
+            )
+
+        return _to_instance(response.parsed)
+
+    async def find_by_name(self, name: str, owner_id: str) -> KeyValueInstance | None:
+        """Look up a Key Value instance by name and owner ID.
+
+        Args:
+            name: Name of the Key Value instance.
+            owner_id: Owner (workspace or team) ID.
+
+        Returns:
+            KeyValueInstance if an instance with that name exists, otherwise None.
+
+        Raises:
+            ClientError: If the API token is unauthorized.
+            ServerError: For 5xx server errors.
+        """
+        response = await list_key_value.asyncio_detailed(
+            client=self.client,
+            name=[name],
+            owner_id=[owner_id],
+        )
+
+        if response.status_code == HTTPStatus.UNAUTHORIZED:
+            raise _unauthorized_error()
+
+        if not isinstance(response.parsed, list):
+            raise _unexpected_error(
+                f"fetching information about Key Value named '{name}'",
+                response.status_code,
+            )
+
+        if len(response.parsed) == 0:
+            return None
+
+        # `name` is unique per-workspace and the search looks for exact matches, not
+        # partial, so there will only ever be zero or one result in the response
+        return _to_instance(response.parsed[0].key_value)
+
+    async def get_connection_info(self, key_value_id: str) -> str:
+        """Get the Redis connection URL for a Key Value instance.
+
+        Returns the internal connection string when running on Render, and
+        the external connection string otherwise (detected via the ``RENDER``
+        environment variable).
+
+        Args:
+            key_value_id: The Render service ID of the Key Value instance.
+
+        Returns:
+            str: A ``redis://`` or ``rediss://`` connection URL.
+
+        Raises:
+            ClientError: If the API token is unauthorized.
+            ServerError: For 5xx server errors.
+        """
+        response = await retrieve_key_value_connection_info.asyncio_detailed(
+            redis_id=key_value_id,
+            client=self.client,
+        )
+
+        if response.status_code == HTTPStatus.UNAUTHORIZED:
+            raise _unauthorized_error()
+
+        if not isinstance(response.parsed, KeyValueConnectionInfo):
+            raise _unexpected_error(
+                f"fetching connection information for Key Value {key_value_id}",
+                response.status_code,
+            )
+
+        if _is_render():
+            return response.parsed.internal_connection_string
+        return response.parsed.external_connection_string
+
+    async def create_instance(self, details: KeyValuePOSTInput) -> KeyValueInstance:
+        """Create a new Key Value instance.
+
+        Args:
+            details: Creation parameters (name, owner ID, plan, etc.).
+
+        Returns:
+            KeyValueInstance: The newly created instance.
+
+        Raises:
+            ClientError: If the API token is unauthorized or the request is invalid.
+            ServerError: For 5xx server errors.
+        """
+        response = await create_key_value.asyncio_detailed(
+            client=self.client,
+            body=details,
+        )
+
+        if response.status_code == HTTPStatus.UNAUTHORIZED:
+            raise _unauthorized_error()
+
+        if not isinstance(response.parsed, KeyValueDetail):
+            raise _unexpected_error(
+                f"creating new Key Value named '{details.name}'",
+                response.status_code,
+            )
+
+        return _to_instance(response.parsed)
+
+    async def update_instance(
+        self, key_value_id: str, update: KeyValuePATCHInput
+    ) -> KeyValueInstance:
+        """Update a Key Value instance's configuration.
+
+        Args:
+            key_value_id: The Render service ID of the Key Value instance.
+            update: Configuration changes to apply.
+
+        Returns:
+            KeyValueInstance: The updated instance.
+
+        Raises:
+            ClientError: If the API token is unauthorized or the request is invalid.
+            ServerError: For 5xx server errors.
+        """
+        response = await update_key_value.asyncio_detailed(
+            redis_id=key_value_id,
+            client=self.client,
+            body=update,
+        )
+
+        if response.status_code == HTTPStatus.UNAUTHORIZED:
+            raise _unauthorized_error()
+
+        if not isinstance(response.parsed, KeyValueDetail):
+            raise _unexpected_error(
+                f"updating Key Value {key_value_id}",
+                response.status_code,
+            )
+
+        return _to_instance(response.parsed)

render/experimental/key_value/compare.py

@@ -0,0 +1,83 @@
+"""Configuration comparison for Key Value instances."""
+
+from render.public_api.models.cidr_block_and_description import (
+    CidrBlockAndDescription,
+)
+from render.public_api.models.key_value_patch_input import KeyValuePATCHInput
+from render.public_api.models.key_value_plan import KeyValuePlan
+from render.public_api.models.maxmemory_policy import MaxmemoryPolicy
+from render.public_api.types import UNSET
+
+from .types import InstanceConfiguration, KeyValueInstance
+
+
+def compare_instance_configuration(
+    desired: InstanceConfiguration,
+    current: KeyValueInstance,
+) -> KeyValuePATCHInput | None:
+    """Compare desired configuration against current state.
+
+    Returns a patch payload containing only the fields that differ, or None if
+    the current configuration already matches the desired configuration.
+
+    Note: Only values that are explicitly set in desired are compared. If a desired
+    value is None, then no change will be made to that value regardless of the current
+    state.
+    """
+    new_plan: KeyValuePlan | None = None
+    if desired.plan is not None and desired.plan != current.plan:
+        new_plan = KeyValuePlan(desired.plan)
+
+    new_maxmemory_policy: MaxmemoryPolicy | None = None
+    if (
+        desired.maxmemory_policy is not None
+        and desired.maxmemory_policy != current.maxmemory_policy
+    ):
+        new_maxmemory_policy = desired.maxmemory_policy
+
+    # None means "caller didn't specify"; an empty list means "clear the allowlist"
+    new_ip_allow_list: list[CidrBlockAndDescription] | None = None
+    if desired.ip_allow_list is not None:
+        new_ip_allow_list = _compare_ip_allow_lists(
+            desired.ip_allow_list, current.ip_allow_list
+        )
+
+    # Use explicit None checks so that an empty ip_allow_list (falsy) still
+    # triggers an update when it differs from the current non-empty list.
+    if (
+        new_plan is not None
+        or new_maxmemory_policy is not None
+        or new_ip_allow_list is not None
+    ):
+        return KeyValuePATCHInput(
+            plan=new_plan if new_plan is not None else UNSET,
+            maxmemory_policy=(
+                new_maxmemory_policy if new_maxmemory_policy is not None else UNSET
+            ),
+            ip_allow_list=new_ip_allow_list if new_ip_allow_list is not None else UNSET,
+        )
+
+    return None
+
+
+def _compare_ip_allow_lists(
+    desired: list[CidrBlockAndDescription],
+    current: list[CidrBlockAndDescription],
+) -> list[CidrBlockAndDescription] | None:
+    """Compare two IP allow lists by CIDR block (descriptions are ignored).
+
+    Returns None if the lists are equivalent, or the desired list if they differ.
+    """
+    if len(desired) != len(current):
+        return desired
+
+    desired_sorted = sorted(desired, key=lambda e: e.cidr_block)
+    current_sorted = sorted(current, key=lambda e: e.cidr_block)
+
+    if any(
+        a.cidr_block != b.cidr_block
+        for a, b in zip(desired_sorted, current_sorted, strict=False)
+    ):
+        return desired
+
+    return None