zeroc-ice 3.7.11__cp314-cp314-macosx_10_15_universal2.whl → 3.8.0.post1__cp314-cp314-macosx_10_15_universal2.whl

Ice/Current.py

@@ -0,0 +1,47 @@
+# Copyright (c) ZeroC, Inc.
+
+from dataclasses import dataclass
+
+from .EncodingVersion import EncodingVersion
+from .IcePyTypes import Connection
+from .Identity import Identity
+from .ObjectAdapter import ObjectAdapter
+from .OperationMode import OperationMode
+
+
+@dataclass(frozen=True)
+class Current:
+    """
+    Provides information about an incoming request being dispatched.
+
+    Attributes
+    ----------
+    adapter : Ice.ObjectAdapter
+        The object adapter that received the request.
+    con : Ice.Connection | None
+        The connection that received the request. It's ``None`` for collocation-optimized dispatches.
+    id : Ice.Identity
+        The identity of the target Ice object.
+    facet : str
+        The facet of the target Ice object.
+    operation : str
+        The name of the operation.
+    mode : Ice.OperationMode
+        The operation mode (idempotent or not).
+    ctx : dict[str, str]
+        The request context.
+    requestId : int
+        The request ID. ``0`` means the request is one-way.
+    encoding : Ice.EncodingVersion
+        The Slice encoding version used to marshal the payload of the request.
+    """
+
+    adapter: ObjectAdapter
+    con: Connection | None
+    id: Identity
+    facet: str
+    operation: str
+    mode: OperationMode
+    ctx: dict[str, str]
+    requestId: int
+    encoding: EncodingVersion

Ice/Dispatch.py

@@ -0,0 +1,122 @@
+# Copyright (c) ZeroC, Inc.
+
+import inspect
+from collections.abc import Callable, Coroutine
+from typing import Any, cast
+
+import IcePy
+
+from .Future import FutureLike
+
+
+def is_future(obj: object) -> bool:
+    return callable(getattr(obj, "add_done_callback", None))
+
+
+def dispatch(cb: IcePy.DispatchCallback, method: Callable, args: list[Any]):
+    """
+    Dispatch a request to the given servant method.
+
+    This function is called by IcePy from an Ice server thread pool thread to dispatch a request to a servant method
+    with the given arguments. The method's result is then sent back to IcePy using the provided callback.
+
+    The method parameter can return:
+    - A direct result, which is immediately sent back via the callback.
+    - A coroutine.
+    - A future.
+
+    If the result is a coroutine and the Ice communicator has a custom coroutine executor, dispatch uses the executor to
+    execute the coroutine, and uses the resulting future to wait for dispatch completion.
+
+    Parameters
+    ----------
+    cb : IcePy.DispatchCallback
+        The callback used to return the result or report an exception to IcePy.
+    method : Callable
+        The servant method to invoke. This method is bound to the servant instance and takes the request parameters as
+        arguments.
+    args : list
+        The request parameters.
+    """
+
+    # Invoke the servant method with the request parameters. Let exceptions propagate to the caller.
+    result = method(*args)
+
+    # If the result is a coroutine and the communicator has a custom coroutine executor, execute the coroutine using
+    # the configured coroutine executor.
+    if inspect.iscoroutine(result):
+        assert len(args) > 0, "args must have at least one argument, current"
+        current = args[-1]
+        eventLoopAdapter = current.adapter.getCommunicator().eventLoopAdapter
+        if eventLoopAdapter:
+            result = eventLoopAdapter.runCoroutine(result)
+            if not is_future(result):
+                raise TypeError("The runCoroutine implementation must return a Future-like object")
+
+    # If the result is a future, attach a done callback to handle dispatch completion.
+    if is_future(result):
+        # Use a more precise type annotation while maintaining runtime behavior.
+        result = cast(FutureLike, result)
+
+        def handle_future_result(future: FutureLike):
+            try:
+                cb.response(future.result())
+            except BaseException as ex:
+                cb.exception(ex)
+
+        result.add_done_callback(handle_future_result)
+
+    # If the result is a coroutine and no custom coroutine executor is available, run the coroutine synchronously in
+    # the current thread using run_coroutine helper function.
+    elif inspect.iscoroutine(result):
+        run_coroutine(cb, result)
+
+    # Otherwise, return the result directly.
+    else:
+        cb.response(result)
+
+
+def run_coroutine(
+    cb: IcePy.DispatchCallback,
+    coroutine: Coroutine[Any, Any, Any],
+    value: object | None = None,
+    exception: BaseException | None = None,
+):
+    """
+    Run a coroutine until completion.
+
+    This function is invoked by the `dispatch` function to execute coroutines when no custom coroutine executor is
+    configured.
+
+    Unlike a general-purpose executor, this function is specifically designed for handling coroutines produced by
+    AMI calls nested in AMD dispatch.
+
+    .. code-block:: python
+
+        async def op(self, current: Ice.Current):
+            await self.prox.ice_pingAsync()
+    """
+    try:
+        if exception:
+            result = coroutine.throw(exception)
+        else:
+            result = coroutine.send(value)
+
+        if is_future(result):
+
+            def handle_future_result(future: FutureLike):
+                try:
+                    run_coroutine(cb, coroutine, value=future.result())
+                except BaseException as ex:
+                    run_coroutine(cb, coroutine, exception=ex)
+
+            # There is a potential recursive call here if the future is already completed.
+            # However, synchronous completion of AMI calls is rare, and this executor is specifically
+            # designed for AMI calls nested in AMD dispatch.
+            result.add_done_callback(handle_future_result)
+        else:
+            raise RuntimeError(f"unexpected value of type {type(result)} returned by coroutine.send()")
+    except StopIteration as ex:
+        cb.response(ex.value)
+    except BaseException as ex:
+        cb.exception(ex)

Ice/DoubleSeq.py

@@ -0,0 +1,10 @@
+# Copyright (c) ZeroC, Inc.
+
+# slice2py version 3.8.0
+
+from __future__ import annotations
+import IcePy
+
+_Ice_DoubleSeq_t = IcePy.defineSequence("::Ice::DoubleSeq", (), IcePy._t_double)
+
+__all__ = ["_Ice_DoubleSeq_t"]

Ice/EncodingVersion.py

@@ -0,0 +1,41 @@
+# Copyright (c) ZeroC, Inc.
+
+# slice2py version 3.8.0
+
+from __future__ import annotations
+import IcePy
+
+from dataclasses import dataclass
+
+
+@dataclass(order=True, unsafe_hash=True)
+class EncodingVersion:
+    """
+    Represents a version of the Slice encoding. Ice supports version 1.0 and 1.1 of this encoding.
+    
+    Attributes
+    ----------
+    major : int
+        The major version of the Slice encoding.
+    minor : int
+        The minor version of the Slice encoding.
+    
+    Notes
+    -----
+        The Slice encoding is also known as the Ice encoding.
+        
+        The Slice compiler generated this dataclass from Slice struct ``::Ice::EncodingVersion``.
+    """
+    major: int = 0
+    minor: int = 0
+
+_Ice_EncodingVersion_t = IcePy.defineStruct(
+    "::Ice::EncodingVersion",
+    EncodingVersion,
+    (),
+    (
+        ("major", (), IcePy._t_byte),
+        ("minor", (), IcePy._t_byte)
+    ))
+
+__all__ = ["EncodingVersion", "_Ice_EncodingVersion_t"]

Ice/EndpointSelectionType.py

@@ -0,0 +1,22 @@
+# Copyright (c) ZeroC, Inc.
+
+from enum import Enum
+
+
+class EndpointSelectionType(Enum):
+    """
+    Determines how the Ice runtime sorts proxy endpoints when establishing a connection.
+    """
+
+    Random = 0
+    """
+    The Ice runtime shuffles the endpoints in a random order.
+    """
+
+    Ordered = 1
+    """
+    The Ice runtime uses the endpoints in the order they appear in the proxy.
+    """
+
+
+__all__ = ["EndpointSelectionType"]

Ice/EventLoopAdapter.py

@@ -0,0 +1,52 @@
+# Copyright (c) ZeroC, Inc.
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Coroutine
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .Future import Future, FutureLike
+
+
+class EventLoopAdapter(ABC):
+    """
+    An adapter that allows applications to execute asynchronous code in a custom event loop.
+    """
+
+    @abstractmethod
+    def runCoroutine(self, coroutine: Coroutine) -> FutureLike:
+        """
+        Runs a coroutine in the application-configured event loop. The Ice run time will call this function to run
+        coroutines returned by async dispatch methods. This function is called from the Ice dispatch thread.
+
+        Parameters
+        ----------
+        coroutine : Coroutine
+            The coroutine to run.
+
+        Returns
+        -------
+        FutureLike
+            A Future-like object that can be used to wait for the completion of the coroutine.
+        """
+        pass
+
+    @abstractmethod
+    def wrapFuture(self, future: Future) -> Awaitable:
+        """
+        Wraps an :class:`Ice.Future` so that it can be awaited in the application event loop.
+        The Ice run time calls this function before returning a future to the application.
+
+        Parameters
+        ----------
+        future : Ice.Future
+            The future to wrap.
+
+        Returns
+        -------
+        Awaitable
+            An awaitable object that can be awaited in the application event loop.
+        """
+        pass

Ice/Exception.py

@@ -0,0 +1,27 @@
+# Copyright (c) ZeroC, Inc.
+
+from builtins import Exception as BuiltinsException
+
+
+class Exception(BuiltinsException):
+    """
+    Abstract base class for all Ice exceptions.
+    It has only two derived classes: :class:`LocalException` and :class:`UserException`.
+    """
+
+    _ice_id: str
+
+    def ice_id(self) -> str:
+        """
+        Returns the type ID of this exception. This corresponds to the Slice type ID for Slice-defined exceptions,
+        and to a fully scoped name for other exceptions. For example: ``"::Ice::CommunicatorDestroyedException"``.
+
+        Returns
+        -------
+        str
+            The type ID of this exception.
+        """
+        return self._ice_id
+
+
+__all__ = ["Exception"]

Ice/FloatSeq.py

@@ -0,0 +1,10 @@
+# Copyright (c) ZeroC, Inc.
+
+# slice2py version 3.8.0
+
+from __future__ import annotations
+import IcePy
+
+_Ice_FloatSeq_t = IcePy.defineSequence("::Ice::FloatSeq", (), IcePy._t_float)
+
+__all__ = ["_Ice_FloatSeq_t"]

Ice/FormatType.py

@@ -0,0 +1,22 @@
+# Copyright (c) ZeroC, Inc.
+
+from enum import Enum
+
+
+class FormatType(Enum):
+    """
+    Specifies the format for marshaling classes and exceptions with the Slice 1.1 encoding.
+    """
+
+    CompactFormat = 0
+    """
+    Favors compactness, but does not support slicing-off unknown slices during unmarshaling.
+    """
+
+    SlicedFormat = 1
+    """
+    Allows slicing-off unknown slices during unmarshaling, at the cost of some extra space in the marshaled data.
+    """
+
+
+__all__ = ["FormatType"]