zeroc-ice 3.7.10__cp312-cp312-win_amd64.whl → 3.8.0__cp312-cp312-win_amd64.whl

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 the order in which the Ice runtime uses the endpoints in a proxy when establishing a connection.
+
+    Enumerators
+    -----------
+    Random : EndpointSelectionType
+        Random causes the endpoints to be arranged in a random order.
+    Ordered : EndpointSelectionType
+        Ordered forces the Ice runtime to use the endpoints in the order they appeared in the proxy.
+    """
+
+    Random = 0
+    Ordered = 1
+
+
+__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:
+        """
+        Run a coroutine in the application configured event loop. The Ice run time will call this method to run
+        coroutines returned by async dispatch methods. This method 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 Ice.Future so that it can be awaited in the application event loop. The Ice run time calls this method
+        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,29 @@
+# Copyright (c) ZeroC, Inc.
+
+from builtins import Exception as BuiltinsException
+
+
+class Exception(BuiltinsException):
+    """
+    The base class for all Ice exceptions.
+    """
+
+    _ice_id: str
+
+    def ice_id(self):
+        """
+        Return the type ID of this exception.
+
+        For exceptions defined in Slice, this corresponds to the Slice type ID.
+        For other exceptions, it is a fully scoped name in the same format.
+        For example: "::Ice::CommunicatorDestroyedException".
+
+        Returns
+        -------
+        str
+            The type ID of the 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,15 @@
+# Copyright (c) ZeroC, Inc.
+
+from enum import Enum
+
+
+class FormatType(Enum):
+    """
+    This enumeration describes the possible formats for classes and exceptions.
+    """
+
+    CompactFormat = 0
+    SlicedFormat = 1
+
+
+__all__ = ["FormatType"]

Ice/Future.py

@@ -0,0 +1,375 @@
+# Copyright (c) ZeroC, Inc.
+
+import asyncio
+import logging
+import threading
+import time
+from collections.abc import Awaitable, Callable, Generator
+from typing import Any, Protocol, Self, TypeVar, overload
+
+from .LocalExceptions import InvocationCanceledException, TimeoutException
+
+# Type variable for the result type of the Future
+_T = TypeVar("_T")
+_T_co = TypeVar("_T_co", covariant=True)
+
+
+class Future(Awaitable[_T]):
+    """
+    A Future object representing the result of an asynchronous operation.
+    """
+
+    def __init__(self):
+        self._result: _T | None = None
+        self._exception: BaseException | None = None
+        self._condition = threading.Condition()
+        self._doneCallbacks = []
+        self._state = Future.StateRunning
+
+    def __await__(self) -> Generator[Any, None, _T]:
+        if not self.done():
+            yield self
+        return self.result()
+
+    def cancel(self):
+        """
+        Attempt to cancel the operation.
+
+        If the operation is already running or has completed, it cannot be cancelled, and the method returns False.
+        Otherwise, the operation is cancelled, and the method returns True.
+
+        Returns
+        -------
+        bool
+            True if the operation was cancelled, False otherwise.
+        """
+        callbacks = []
+        with self._condition:
+            if self._state == Future.StateDone:
+                return False
+
+            if self._state == Future.StateCancelled:
+                return True
+
+            self._state = Future.StateCancelled
+            callbacks = self._doneCallbacks
+            self._doneCallbacks = []
+            self._condition.notify_all()
+
+        self._callCallbacks(callbacks)
+
+        return True
+
+    def cancelled(self):
+        """
+        Check if the future has been cancelled.
+
+        Returns
+        -------
+        bool
+            True if the future was cancelled using `cancel()`, otherwise False.
+        """
+        with self._condition:
+            return self._state == Future.StateCancelled
+
+    def running(self):
+        """
+        Check if the future is still running.
+
+        Returns
+        -------
+        bool
+            True if the operation is currently executing and cannot be cancelled,
+            otherwise False.
+        """
+        with self._condition:
+            return self._state == Future.StateRunning
+
+    def done(self):
+        """
+        Check if the future has completed or been cancelled.
+
+        Returns
+        -------
+        bool
+            True if the operation has completed (successfully or with an exception)
+            or has been cancelled, otherwise False.
+        """
+        with self._condition:
+            return self._state in [Future.StateCancelled, Future.StateDone]
+
+    def add_done_callback(self, fn: Callable) -> None:
+        """
+        Attach a callback to be executed when the future completes.
+
+        The callback `fn` is called with the future as its only argument once the future completes or is cancelled.
+        Registered callbacks are executed in the order they were added.
+
+        If the future is already complete, `fn` is called immediately from the calling thread.
+
+        Parameters
+        ----------
+        fn : callable
+            The function to execute upon completion. Takes the future as its argument.
+        """
+        with self._condition:
+            if self._state == Future.StateRunning:
+                self._doneCallbacks.append(fn)
+                return
+        fn(self)
+
+    def result(self, timeout: int | float | None = None) -> _T:
+        """
+        Retrieve the result of the future.
+
+        If the operation has not completed, this method waits up to `timeout` seconds for it to finish. If the
+        timeout is reached, a `TimeoutException` is raised.
+
+        If the future was cancelled before completing, an `InvocationCanceledException` is raised.
+
+        If the operation raised an exception, this method raises the same exception.
+
+        Parameters
+        ----------
+        timeout : int | float, optional
+            Maximum time (in seconds) to wait for the result. If `None`, the method waits indefinitely until the
+            operation completes.
+
+        Returns
+        -------
+        object
+            The result of the operation.
+
+        Raises
+        ------
+        TimeoutException
+            If the operation has not completed within the specified timeout.
+        InvocationCanceledException
+            If the operation was cancelled before completing.
+        Exception
+            If the operation raised an exception.
+        """
+        with self._condition:
+            if not self._wait(timeout, lambda: self._state == Future.StateRunning):
+                raise TimeoutException()
+
+            if self._state == Future.StateCancelled:
+                raise InvocationCanceledException()
+            elif self._exception:
+                raise self._exception
+            else:
+                # We can't check if _result is None here, because it is valid to have a result of None.
+                # i.e. Future[None]
+                return self._result  # type: ignore[return-value]
+
+    def exception(self, timeout: int | float | None = None) -> BaseException | None:
+        """
+        Retrieve the exception raised by the operation.
+
+        If the operation has not completed, this method waits up to `timeout` seconds for it to finish. If the timeout
+        is reached, a `TimeoutException` is raised.
+
+        If the future was cancelled before completing, an `InvocationCanceledException` is raised.
+
+        If the operation completed successfully without raising an exception, `None` is returned.
+
+        Parameters
+        ----------
+        timeout : int | float, optional
+            Maximum time (in seconds) to wait for the exception. If `None`, the method waits indefinitely until the
+            operation completes.
+
+        Returns
+        -------
+        BaseException or None
+            The exception raised by the operation, or `None` if the operation completed successfully.
+
+        Raises
+        ------
+        TimeoutException
+            If the operation has not completed within the specified timeout.
+        InvocationCanceledException
+            If the operation was cancelled before completing.
+        """
+        with self._condition:
+            if not self._wait(timeout, lambda: self._state == Future.StateRunning):
+                raise TimeoutException()
+            if self._state == Future.StateCancelled:
+                raise InvocationCanceledException()
+            else:
+                return self._exception
+
+    def set_result(self, result: _T):
+        """
+        Set the result of the future and mark it as completed.
+
+        This method stores the provided `result` and transitions the future's state to "done". Any registered
+        callbacks are executed after the state update.
+
+        If the future is not in a running state, this method has no effect.
+
+        Parameters
+        ----------
+        result : object
+            The result value to store in the future.
+        """
+        callbacks = []
+        with self._condition:
+            if self._state != Future.StateRunning:
+                return
+            self._result = result
+            self._state = Future.StateDone
+            callbacks = self._doneCallbacks
+            self._doneCallbacks = []
+            self._condition.notify_all()
+
+        self._callCallbacks(callbacks)
+
+    def set_exception(self, ex: BaseException):
+        """
+        Set an exception for the future and mark it as completed.
+
+        This method stores the provided exception `ex` and transitions the future's state to "done". Any registered
+        callbacks are executed after the state update.
+
+        If the future is not in a running state, this method has no effect.
+
+        Parameters
+        ----------
+        ex : BaseException
+            The exception to store in the future.
+        """
+        callbacks = []
+        with self._condition:
+            if self._state != Future.StateRunning:
+                return
+            self._exception = ex
+            self._state = Future.StateDone
+            callbacks = self._doneCallbacks
+            self._doneCallbacks = []
+            self._condition.notify_all()
+        self._callCallbacks(callbacks)
+
+    @staticmethod
+    def completed(result: _T) -> "Future[_T]":
+        f = Future()
+        f.set_result(result)
+        return f
+
+    def _wait(self, timeout: float | None, testFn: Callable[[], bool]) -> bool:
+        # Must be called with _condition acquired
+
+        while testFn():
+            if timeout:
+                start = time.time()
+                self._condition.wait(timeout)
+                # Subtract the elapsed time so far from the timeout
+                timeout -= time.time() - start
+                if timeout <= 0:
+                    return False
+            else:
+                self._condition.wait()
+
+        return True
+
+    def _callCallbacks(self, callbacks: list[Callable[[Self], None]]):
+        for callback in callbacks:
+            try:
+                callback(self)
+            except Exception:
+                logging.getLogger("Ice.Future").exception("done callback raised exception")
+
+    StateRunning = "running"
+    StateCancelled = "cancelled"
+    StateDone = "done"
+
+
+def wrap_future(future: Future | asyncio.Future, *, loop: asyncio.AbstractEventLoop | None = None) -> asyncio.Future:
+    """
+    Wrap an :class:`Ice.Future` object into an ``asyncio.Future``.
+
+    This function converts an Ice.Future into an asyncio.Future to allow integration of Ice's
+    asynchronous operations with Python's asyncio framework. If the provided future is already
+    an asyncio.Future, it is returned unchanged.
+
+    If the Ice.Future is already completed, the asyncio.Future is immediately resolved. Otherwise,
+    completion callbacks are registered to ensure that the asyncio.Future reflects the state of the
+    Ice.Future, including result propagation, exception handling, and cancellation.
+
+    Parameters
+    ----------
+    future : Future | asyncio.Future
+        The Ice.Future object to wrap. If an asyncio.Future is passed, it is returned as-is.
+
+    loop : asyncio.AbstractEventLoop, optional
+        The event loop to associate with the asyncio.Future. If not provided, the current event loop
+        is used.
+
+    Returns
+    -------
+    asyncio.Future
+        A future that mirrors the state of the input Ice.Future.
+
+    Raises
+    ------
+    AssertionError
+        If `future` is not an instance of Ice.Future or asyncio.Future.
+    """
+
+    if isinstance(future, asyncio.Future):
+        return future
+
+    assert isinstance(future, Future), "Ice.Future is expected, got {!r}".format(future)
+
+    @overload
+    def forwardCompletion(sourceFuture: Future, targetFuture: asyncio.Future): ...
+
+    @overload
+    def forwardCompletion(sourceFuture: asyncio.Future, targetFuture: Future): ...
+
+    def forwardCompletion(sourceFuture: Future | asyncio.Future, targetFuture: Future | asyncio.Future):
+        if not targetFuture.done():
+            if sourceFuture.cancelled():
+                targetFuture.cancel()
+            elif (sourceException := sourceFuture.exception()) is not None:
+                targetFuture.set_exception(sourceException)
+            else:
+                targetFuture.set_result(sourceFuture.result())
+
+    if loop is None:
+        loop = asyncio.get_event_loop()
+    asyncioFuture = loop.create_future()
+
+    if future.done():
+        # As long as no done callbacks are registered, completing the asyncio future should be thread safe
+        # even if the future is constructed with a loop which isn't the current thread's loop.
+        forwardCompletion(future, asyncioFuture)
+    else:
+        asyncioFuture.add_done_callback(lambda f: forwardCompletion(asyncioFuture, future))
+        future.add_done_callback(lambda f: loop.call_soon_threadsafe(forwardCompletion, future, asyncioFuture))
+
+    return asyncioFuture
+
+
+class FutureLike(Protocol[_T_co]):
+    """A protocol that defines the interface for objects that behave like a Future."""
+
+    def add_done_callback(self, callback: Callable[["FutureLike"], Any], /) -> None:
+        """Add a callback to be run when the Future is done.
+
+        Args:
+            callback: A callable that takes the Future object as its only argument.
+                    Will be called when the Future completes (successfully,
+                    with exception, or cancelled).
+
+        Note: Using positional-only parameter (/) to match both asyncio and
+            concurrent.futures implementations regardless of parameter name.
+        """
+        ...
+
+    def result(self, timeout: int | float | None = None) -> _T_co:
+        """Return the result of the Future."""
+        ...
+
+
+__all__ = ["Future", "wrap_future", "FutureLike"]