volcano-sdk-python 0.10.0__py3-none-any.whl → 0.10.2__py3-none-any.whl

volcano_sdk/_function_resolution.py

@@ -28,7 +28,14 @@ _LOCK_STRIPES = 64
 
 
 def _now() -> float:
-    """Read the clock lifetimes are measured against, immune to wall-clock jumps."""
+    """Read the clock used for cache lifetimes.
+
+    Returns
+    -------
+    float
+        Monotonic seconds, unaffected by wall-clock adjustments.
+
+    """
     return time.monotonic()
 
 
@@ -62,7 +69,14 @@ _stripes = [threading.Lock() for _ in range(_LOCK_STRIPES)]
 
 
 def resolve_lock(api_url: str, authorization: str, name: str) -> threading.Lock:
-    """Return the lock that serializes resolving one name."""
+    """Select the lock for resolving one name.
+
+    Returns
+    -------
+    threading.Lock
+        A shared stripe keyed by API URL, credential, and function name.
+
+    """
     return _stripes[hash((api_url, authorization, name)) % _LOCK_STRIPES]
 
 
@@ -75,6 +89,12 @@ def valid_invoke_url(value: object, api_url: str) -> str | None:
 
     Anything unusable yields None so the caller falls back to the API path. A
     malformed server response must not raise out of invoke().
+
+    Returns
+    -------
+    str or None
+        The accepted URL unchanged, or None to use the API endpoint.
+
     """
     if not isinstance(value, str):
         return None
@@ -91,6 +111,12 @@ def _absolute_url_scheme(value: str) -> str:
 
     Unparseable input yields "" rather than raising, so a malformed URL reads
     as unusable to every caller.
+
+    Returns
+    -------
+    str
+        The lowercase scheme, or an empty string for an invalid authority or URL.
+
     """
     if not value or any(character.isspace() for character in value):
         return ""
@@ -105,7 +131,14 @@ def _absolute_url_scheme(value: str) -> str:
 
 
 def lookup(api_url: str, authorization: str, name: str) -> CachedOutcome | None:
-    """Return the cached outcome for a name, or None when it must be resolved."""
+    """Look up a function within its API and credential scope.
+
+    Returns
+    -------
+    CachedOutcome or None
+        An unexpired resolution or remembered miss; None requires a new resolve.
+
+    """
     key = (api_url, authorization, name)
     now = _now()
     with _lock:

volcano_sdk/_generated/api/projects/get_project_logo.py

@@ -9,6 +9,8 @@ from ...types import Response, UNSET
 from ... import errors
 
 from ...models.error import Error
+from ...types import File, FileTypes
+from io import BytesIO
 from typing import cast
 from uuid import UUID
 
@@ -34,7 +36,16 @@ def _get_kwargs(
 
 
 
-def _parse_response(*, client: AuthenticatedClient | Client, response: httpx.Response) -> Error | None:
+def _parse_response(*, client: AuthenticatedClient | Client, response: httpx.Response) -> Error | File | None:
+    if response.status_code == 200:
+        response_200 = File(
+             payload = BytesIO(response.content)
+        )
+
+
+
+        return response_200
+
     if response.status_code == 404:
         response_404 = Error.from_dict(response.json())
 
@@ -48,7 +59,7 @@ def _parse_response(*, client: AuthenticatedClient | Client, response: httpx.Res
         return None
 
 
-def _build_response(*, client: AuthenticatedClient | Client, response: httpx.Response) -> Response[Error]:
+def _build_response(*, client: AuthenticatedClient | Client, response: httpx.Response) -> Response[Error | File]:
     return Response(
         status_code=HTTPStatus(response.status_code),
         content=response.content,
@@ -62,7 +73,7 @@ def sync_detailed(
     *,
     client: AuthenticatedClient | Client,
 
-) -> Response[Error]:
+) -> Response[Error | File]:
     """ Get the project logo image
 
      Returns the raw logo image stored in the project's storage folder. This
@@ -79,7 +90,7 @@ def sync_detailed(
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Response[Error]
+        Response[Error | File]
      """
 
 
@@ -99,7 +110,7 @@ def sync(
     *,
     client: AuthenticatedClient | Client,
 
-) -> Error | None:
+) -> Error | File | None:
     """ Get the project logo image
 
      Returns the raw logo image stored in the project's storage folder. This
@@ -116,7 +127,7 @@ def sync(
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Error
+        Error | File
      """
 
 
@@ -131,7 +142,7 @@ async def asyncio_detailed(
     *,
     client: AuthenticatedClient | Client,
 
-) -> Response[Error]:
+) -> Response[Error | File]:
     """ Get the project logo image
 
      Returns the raw logo image stored in the project's storage folder. This
@@ -148,7 +159,7 @@ async def asyncio_detailed(
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Response[Error]
+        Response[Error | File]
      """
 
 
@@ -168,7 +179,7 @@ async def asyncio(
     *,
     client: AuthenticatedClient | Client,
 
-) -> Error | None:
+) -> Error | File | None:
     """ Get the project logo image
 
      Returns the raw logo image stored in the project's storage folder. This
@@ -185,7 +196,7 @@ async def asyncio(
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Error
+        Error | File
      """
 
 

volcano_sdk/_generated/api/storage_objects/download_public_file.py

@@ -9,6 +9,8 @@ from ...types import Response, UNSET
 from ... import errors
 
 from ...models.error import Error
+from ...types import File, FileTypes
+from io import BytesIO
 from typing import cast
 from uuid import UUID
 
@@ -36,7 +38,16 @@ def _get_kwargs(
 
 
 
-def _parse_response(*, client: AuthenticatedClient | Client, response: httpx.Response) -> Any | Error | None:
+def _parse_response(*, client: AuthenticatedClient | Client, response: httpx.Response) -> Any | Error | File | None:
+    if response.status_code == 200:
+        response_200 = File(
+             payload = BytesIO(response.content)
+        )
+
+
+
+        return response_200
+
     if response.status_code == 206:
         response_206 = cast(Any, None)
         return response_206
@@ -58,7 +69,7 @@ def _parse_response(*, client: AuthenticatedClient | Client, response: httpx.Res
         return None
 
 
-def _build_response(*, client: AuthenticatedClient | Client, response: httpx.Response) -> Response[Any | Error]:
+def _build_response(*, client: AuthenticatedClient | Client, response: httpx.Response) -> Response[Any | Error | File]:
     return Response(
         status_code=HTTPStatus(response.status_code),
         content=response.content,
@@ -74,7 +85,7 @@ def sync_detailed(
     *,
     client: AuthenticatedClient | Client,
 
-) -> Response[Any | Error]:
+) -> Response[Any | Error | File]:
     """ Download a public file (no authentication required)
 
      Download a file that has been marked as public. This endpoint requires NO authentication.
@@ -111,7 +122,7 @@ def sync_detailed(
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Response[Any | Error]
+        Response[Any | Error | File]
      """
 
 
@@ -135,7 +146,7 @@ def sync(
     *,
     client: AuthenticatedClient | Client,
 
-) -> Any | Error | None:
+) -> Any | Error | File | None:
     """ Download a public file (no authentication required)
 
      Download a file that has been marked as public. This endpoint requires NO authentication.
@@ -172,7 +183,7 @@ def sync(
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Any | Error
+        Any | Error | File
      """
 
 
@@ -191,7 +202,7 @@ async def asyncio_detailed(
     *,
     client: AuthenticatedClient | Client,
 
-) -> Response[Any | Error]:
+) -> Response[Any | Error | File]:
     """ Download a public file (no authentication required)
 
      Download a file that has been marked as public. This endpoint requires NO authentication.
@@ -228,7 +239,7 @@ async def asyncio_detailed(
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Response[Any | Error]
+        Response[Any | Error | File]
      """
 
 
@@ -252,7 +263,7 @@ async def asyncio(
     *,
     client: AuthenticatedClient | Client,
 
-) -> Any | Error | None:
+) -> Any | Error | File | None:
     """ Download a public file (no authentication required)
 
      Download a file that has been marked as public. This endpoint requires NO authentication.
@@ -289,7 +300,7 @@ async def asyncio(
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Any | Error
+        Any | Error | File
      """
 
 

volcano_sdk/_lock_guard.py

@@ -69,19 +69,26 @@ class LockGuard:
 
     @property
     def lease(self) -> LockLease:
-        """Return the latest successfully renewed immutable lease."""
+        """The latest successfully renewed immutable lease."""
         with self._state_lock:
             return self._lease
 
     @property
     def lost(self) -> bool:
-        """Return whether renewal failed or the latest lease expired."""
+        """Whether renewal failed, the lease expired, or the guard closed."""
         with self._state_lock:
             self._expire_if_needed_locked(_lease_now())
             return self._lost.is_set()
 
     def wait_lost(self, timeout: float | None = None) -> bool:
-        """Wait until ownership is lost or the timeout expires."""
+        """Wait until ownership is lost or the timeout expires.
+
+        Returns
+        -------
+        bool
+            True when the guard reports lost ownership, False on timeout.
+
+        """
         timeout_deadline = None if timeout is None else _lease_now() + timeout
         while True:
             with self._state_lock:

volcano_sdk/_lock_renewer.py

@@ -17,7 +17,15 @@ def _renewal_jitter() -> float:
 
 
 def renewal_delay(ttl: int, *, remaining: float) -> float:
-    """Choose a jittered renewal time inside the current lease window."""
+    """Choose a jittered renewal time inside the current lease window.
+
+    Returns
+    -------
+    float
+        Seconds before renewal, capped by the remaining safe request window.
+        Zero requests immediate renewal.
+
+    """
     latest = max(
         0.0,
         remaining - RENEWAL_SAFETY_MARGIN_SECONDS - RENEWAL_REQUEST_BUDGET_SECONDS,

volcano_sdk/_log_response.py

@@ -0,0 +1,84 @@
+"""Validate log response containers before generated model normalization."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from .models import JSONValue
+
+INVALID_LOG_RESPONSE = "Expected a complete log response"
+
+
+def response_values(payload: object) -> Mapping[str, object]:
+    """Require a JSON object for the response envelope.
+
+    Raises:
+        TypeError: The response envelope is not an object.
+
+    Returns:
+        The response fields without normalizing their values.
+
+    """
+    if not isinstance(payload, Mapping):
+        raise TypeError(INVALID_LOG_RESPONSE)
+    return cast("Mapping[str, object]", payload)
+
+
+def response_data(values: Mapping[str, object]) -> tuple[Mapping[str, JSONValue], ...]:
+    """Require a list of objects without coercing empty mappings into lists.
+
+    Raises:
+        TypeError: The rows are not a list of objects.
+
+    Returns:
+        The validated rows in their original order.
+
+    """
+    raw_data = values.get("data")
+    if not isinstance(raw_data, list):
+        raise TypeError(INVALID_LOG_RESPONSE)
+    data = cast("list[object]", raw_data)
+    if any(not isinstance(item, Mapping) for item in data):
+        raise TypeError(INVALID_LOG_RESPONSE)
+    return tuple(cast("Mapping[str, JSONValue]", item) for item in data)
+
+
+def search_metadata(values: Mapping[str, object]) -> tuple[int, bool, str | None]:
+    """Require search pagination fields without coercing their values.
+
+    Raises:
+        TypeError: Required metadata is missing or has an invalid type.
+
+    Returns:
+        The page limit, continuation flag, and optional cursor.
+
+    """
+    limit = values.get("limit")
+    has_more = values.get("has_more")
+    next_cursor = values.get("next_cursor")
+    if (
+        not isinstance(limit, int)
+        or isinstance(limit, bool)
+        or not isinstance(has_more, bool)
+        or (next_cursor is not None and not isinstance(next_cursor, str))
+    ):
+        raise TypeError(INVALID_LOG_RESPONSE)
+    return limit, has_more, next_cursor
+
+
+def activity_total(values: Mapping[str, object]) -> int:
+    """Require the activity total without treating booleans as integers.
+
+    Raises:
+        TypeError: The total is missing or is not an integer.
+
+    Returns:
+        The total reported by the server.
+
+    """
+    total = values.get("total")
+    if not isinstance(total, int) or isinstance(total, bool):
+        raise TypeError(INVALID_LOG_RESPONSE)
+    return total

volcano_sdk/_realtime_fetch_worker.py

@@ -3,16 +3,17 @@
 from __future__ import annotations
 
 import asyncio
+from collections.abc import Mapping
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Generic, TypeVar
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+from .models import JSONValue
 
 if TYPE_CHECKING:
     from collections.abc import Awaitable, Callable
 
-    from .realtime import _PostgresFetchRequest
-
 FallbackT = TypeVar("FallbackT")
-PostgresRecord = dict[str, Any]
+PostgresRecord = Mapping[str, JSONValue]
 _WORKER_CLOSED = "Postgres fetch worker is closed"
 _INVALID_QUEUE_LIMIT = "queue_limit must be positive"
 _INVALID_BATCH_WINDOW = "batch_window_seconds cannot be negative"
@@ -20,11 +21,21 @@ _INVALID_BATCH_SIZE = "max_batch_size must be between 1 and queue_limit"
 _INVALID_RESULT_COUNT = "Postgres fetch returned an unexpected result count"
 
 
+@dataclass(frozen=True, slots=True)
+class PostgresFetchRequest:
+    """Capture the database, credential, and row identity for a queued fetch."""
+
+    database_name: str
+    access_token: str
+    table: str
+    row_id: JSONValue
+
+
 @dataclass(frozen=True, slots=True)
 class PostgresFetchJob(Generic[FallbackT]):
     """Pair a captured row request with its lightweight fallback."""
 
-    request: _PostgresFetchRequest | None
+    request: PostgresFetchRequest | None
     fallback: FallbackT
 
 
@@ -45,13 +56,32 @@ class _StopWorker:
 _STOP_WORKER = _StopWorker()
 
 
+async def _wait_for_close(
+    task: asyncio.Task[None],
+    stop_task: asyncio.Task[None],
+) -> None:
+    completed, _pending = await asyncio.wait(
+        (task, stop_task),
+        return_when=asyncio.FIRST_COMPLETED,
+    )
+    if task in completed:
+        try:
+            task.result()
+        except BaseException:
+            _ = stop_task.cancel()
+            _ = await asyncio.gather(stop_task, return_exceptions=True)
+            raise
+    await asyncio.shield(stop_task)
+    await asyncio.shield(task)
+
+
 class PostgresFetchWorker(Generic[FallbackT]):
     """Fetch queued rows serially and deliver outcomes in enqueue order."""
 
     def __init__(
         self,
         fetch: Callable[
-            [tuple[_PostgresFetchRequest, ...]],
+            [tuple[PostgresFetchRequest, ...]],
             Awaitable[tuple[PostgresRecord | None, ...]],
         ],
         deliver: Callable[[PostgresFetchOutcome[FallbackT]], Awaitable[None]],
@@ -60,27 +90,47 @@ class PostgresFetchWorker(Generic[FallbackT]):
         batch_window_seconds: float = 0,
         max_batch_size: int = 1,
     ) -> None:
-        """Create a worker with a fixed pending-job limit."""
+        """Create a worker with a fixed pending-job limit.
+
+        Raises
+        ------
+        ValueError
+            The queue limit is not positive, the batch window is negative,
+            or the batch size is outside the range from one to the queue limit.
+
+        """
         if queue_limit <= 0:
             raise ValueError(_INVALID_QUEUE_LIMIT)
         if batch_window_seconds < 0:
             raise ValueError(_INVALID_BATCH_WINDOW)
         if not 1 <= max_batch_size <= queue_limit:
             raise ValueError(_INVALID_BATCH_SIZE)
-        self._fetch = fetch
-        self._deliver = deliver
-        self._batch_window_seconds = batch_window_seconds
-        self._max_batch_size = max_batch_size
+        self._fetch: Callable[
+            [tuple[PostgresFetchRequest, ...]],
+            Awaitable[tuple[PostgresRecord | None, ...]],
+        ] = fetch
+        self._deliver: Callable[[PostgresFetchOutcome[FallbackT]], Awaitable[None]] = (
+            deliver
+        )
+        self._batch_window_seconds: float = batch_window_seconds
+        self._max_batch_size: int = max_batch_size
         self._queue: asyncio.Queue[PostgresFetchJob[FallbackT] | _StopWorker] = (
             asyncio.Queue(maxsize=queue_limit)
         )
-        self._state_lock = asyncio.Lock()
+        self._state_lock: asyncio.Lock = asyncio.Lock()
         self._task: asyncio.Task[None] | None = None
         self._stop_task: asyncio.Task[None] | None = None
-        self._closed = False
+        self._closed: bool = False
 
     async def enqueue(self, job: PostgresFetchJob[FallbackT]) -> None:
-        """Queue one fetch, applying backpressure when the queue is full."""
+        """Queue one fetch, applying backpressure when the queue is full.
+
+        Raises
+        ------
+        RuntimeError
+            The worker has closed or was cancelled before accepting the job.
+
+        """
         async with self._state_lock:
             if self._closed:
                 raise RuntimeError(_WORKER_CLOSED)
@@ -102,7 +152,7 @@ class PostgresFetchWorker(Generic[FallbackT]):
                 self._stop_task = asyncio.create_task(self._queue.put(_STOP_WORKER))
             stop_task = self._stop_task
         if task is not None and stop_task is not None:
-            await self._wait_for_close(task, stop_task)
+            await _wait_for_close(task, stop_task)
 
     async def abort(self) -> None:
         """Discard obsolete jobs and stop without waiting for row fetches."""
@@ -110,14 +160,14 @@ class PostgresFetchWorker(Generic[FallbackT]):
         task = self._task
         stop_task = self._stop_task
         if stop_task is not None and not stop_task.done():
-            stop_task.cancel()
+            _ = stop_task.cancel()
         if task is not None and not task.done():
-            task.cancel()
+            _ = task.cancel()
         pending = tuple(
             candidate for candidate in (task, stop_task) if candidate is not None
         )
         if pending:
-            await asyncio.gather(*pending, return_exceptions=True)
+            _ = await asyncio.gather(*pending, return_exceptions=True)
         self._discard_pending()
 
     def _raise_worker_failure(self) -> None:
@@ -138,8 +188,8 @@ class PostgresFetchWorker(Generic[FallbackT]):
             )
         finally:
             if not put_task.done():
-                put_task.cancel()
-                await asyncio.gather(put_task, return_exceptions=True)
+                _ = put_task.cancel()
+                _ = await asyncio.gather(put_task, return_exceptions=True)
         if task in completed:
             if task.cancelled():
                 raise RuntimeError(_WORKER_CLOSED)
@@ -148,28 +198,9 @@ class PostgresFetchWorker(Generic[FallbackT]):
 
     def _discard_pending(self) -> None:
         while not self._queue.empty():
-            self._queue.get_nowait()
+            _ = self._queue.get_nowait()
             self._queue.task_done()
 
-    async def _wait_for_close(
-        self,
-        task: asyncio.Task[None],
-        stop_task: asyncio.Task[None],
-    ) -> None:
-        completed, _pending = await asyncio.wait(
-            (task, stop_task),
-            return_when=asyncio.FIRST_COMPLETED,
-        )
-        if task in completed:
-            try:
-                task.result()
-            except BaseException:
-                stop_task.cancel()
-                await asyncio.gather(stop_task, return_exceptions=True)
-                raise
-        await asyncio.shield(stop_task)
-        await asyncio.shield(task)
-
     async def _run(self) -> None:
         pending: PostgresFetchJob[FallbackT] | _StopWorker | None = None
         while True:
@@ -196,15 +227,8 @@ class PostgresFetchWorker(Generic[FallbackT]):
             return None
         deadline = asyncio.get_running_loop().time() + self._batch_window_seconds
         while len(batch) < self._max_batch_size:
-            remaining = deadline - asyncio.get_running_loop().time()
-            if remaining <= 0:
-                return None
-            try:
-                async with asyncio.timeout(remaining):
-                    candidate = await self._queue.get()
-            except TimeoutError:
-                return None
-            if isinstance(candidate, _StopWorker):
+            candidate = await self._next_before(deadline)
+            if candidate is None or isinstance(candidate, _StopWorker):
                 return candidate
             request = candidate.request
             if (
@@ -216,10 +240,23 @@ class PostgresFetchWorker(Generic[FallbackT]):
             batch.append(candidate)
         return None
 
+    async def _next_before(
+        self,
+        deadline: float,
+    ) -> PostgresFetchJob[FallbackT] | _StopWorker | None:
+        remaining = deadline - asyncio.get_running_loop().time()
+        if remaining <= 0:
+            return None
+        try:
+            async with asyncio.timeout(remaining):
+                return await self._queue.get()
+        except TimeoutError:
+            return None
+
     @staticmethod
     def _same_fetch(
-        first: _PostgresFetchRequest,
-        request: _PostgresFetchRequest,
+        first: PostgresFetchRequest,
+        request: PostgresFetchRequest,
     ) -> bool:
         return (
             first.database_name,
@@ -234,7 +271,7 @@ class PostgresFetchWorker(Generic[FallbackT]):
     @staticmethod
     def _repeats_row(
         batch: list[PostgresFetchJob[FallbackT]],
-        request: _PostgresFetchRequest,
+        request: PostgresFetchRequest,
     ) -> bool:
         return any(
             job.request is not None and job.request.row_id == request.row_id
@@ -254,12 +291,19 @@ class PostgresFetchWorker(Generic[FallbackT]):
             return_exceptions=True,
         )
         if isinstance(result, BaseException):
-            if not isinstance(result, Exception):
-                raise result
-            for job in jobs:
-                await self._deliver(PostgresFetchOutcome(job=job, error=result))
+            await self._deliver_failure(jobs, result)
             return
         if len(result) != len(jobs):
             raise RuntimeError(_INVALID_RESULT_COUNT)
         for job, record in zip(jobs, result, strict=True):
             await self._deliver(PostgresFetchOutcome(job=job, record=record))
+
+    async def _deliver_failure(
+        self,
+        jobs: list[PostgresFetchJob[FallbackT]],
+        error: BaseException,
+    ) -> None:
+        if not isinstance(error, Exception):
+            raise error
+        for job in jobs:
+            await self._deliver(PostgresFetchOutcome(job=job, error=error))