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

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) -> bool:
+        """
+        Attempts to cancel this future.
+
+        If this future is already running or has completed, it cannot be cancelled.
+
+        Returns
+        -------
+        bool
+            ``True`` if this future 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) -> bool:
+        """
+        Checks if this future has been cancelled.
+
+        Returns
+        -------
+        bool
+            ``True`` if this future was cancelled, otherwise ``False``.
+        """
+        with self._condition:
+            return self._state == Future.StateCancelled
+
+    def running(self) -> bool:
+        """
+        Checks if this future is still running.
+
+        Returns
+        -------
+        bool
+            ``True`` if this future is currently executing, otherwise ``False``.
+        """
+        with self._condition:
+            return self._state == Future.StateRunning
+
+    def done(self) -> bool:
+        """
+        Checks if this future has completed or been cancelled.
+
+        Returns
+        -------
+        bool
+            ``True`` if this future has completed (either 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[["Future"], Any]) -> None:
+        """
+        Attaches a callback function which will be called when this future completes or is cancelled.
+        If this future is already complete, ``fn`` is called immediately from the calling thread.
+
+        Parameters
+        ----------
+        fn : Callable[[Future], Any]
+            The function to execute upon completion.
+        """
+        with self._condition:
+            if self._state == Future.StateRunning:
+                self._doneCallbacks.append(fn)
+                return
+        fn(self)
+
+    def result(self, timeout: int | float | None = None) -> _T:
+        """
+        Retrieves the result of this future's operation.
+
+        If the operation has not completed, this function will wait up to ``timeout``-many seconds for it to finish.
+        If the operation raised an exception, this function raises the same exception.
+
+        Parameters
+        ----------
+        timeout : int | float | None, optional
+            Maximum time (in seconds) to wait for the result.
+            If ``None`` (the default), this function 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:
+        """
+        Retrieves the exception raised by this future's operation.
+
+        If the operation has not completed, this function will wait up to ``timeout``-many seconds for it to finish.
+
+        Parameters
+        ----------
+        timeout : int | float | None, optional
+            Maximum time (in seconds) to wait for the exception.
+            If ``None`` (the default), this function waits indefinitely until the operation completes.
+
+        Returns
+        -------
+        BaseException | 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):
+        """
+        Sets the result of this future and marks it as completed.
+
+        This function 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 function 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):
+        """
+        Sets an exception for this future and marks it as completed.
+
+        This function 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 function 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:
+    """
+    Wraps an :class:`Ice.Future` object into an ``asyncio.Future``.
+
+    This function converts an :class:`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 :class:`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
+    :class:`Ice.Future`, including result propagation, exception handling, and cancellation.
+
+    Parameters
+    ----------
+    future : Future | asyncio.Future
+        The future object to wrap. If an ``asyncio.Future`` is passed, it is returned as-is.
+
+    loop : asyncio.AbstractEventLoop | None, 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 provided :class:`Ice.Future`.
+
+    Raises
+    ------
+    AssertionError
+        If ``future`` is not an instance of :class:`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 this 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 an interface for objects that behave like a ``Future``."""
+
+    # We use a positional-only parameter (/) to match both `asyncio` and `concurrent.futures`
+    # implementations (since the two implementations use different parameter names).
+    def add_done_callback(self, callback: Callable[["FutureLike"], Any], /) -> None:
+        """
+        Adds a callback to be run when the ``Future`` is done.
+
+        Parameters
+        ----------
+        callback: Callable[[FutureLike], Any]
+            A callable that takes the ``Future`` object as its only argument.
+            Will be called when the ``Future`` completes (successfully, with exception, or cancelled).
+        """
+        ...
+
+    def result(self, timeout: int | float | None = None) -> _T_co:
+        """
+        Retrieves the result of the ``Future``.
+
+        If the ``Future`` has not completed, this function will wait up to ``timeout``-many seconds for it to finish.
+
+        Parameters
+        ----------
+        timeout : int | float | None, optional
+            Maximum time (in seconds) to wait for the result.
+            If ``None`` (the default), this function waits indefinitely until the operation completes.
+
+        Returns
+        -------
+        object
+            The result of the ``Future``.
+        """
+        ...
+
+
+__all__ = ["Future", "wrap_future", "FutureLike"]

Ice/IcePyTypes.py

@@ -0,0 +1,49 @@
+# Copyright (c) ZeroC, Inc.
+
+# These are the public types we re-export from IcePy.
+
+from IcePy import (
+    BatchRequest,
+    Connection,
+    ConnectionInfo,
+    Endpoint,
+    EndpointInfo,
+    IPConnectionInfo,
+    IPEndpointInfo,
+    NativePropertiesAdmin,
+    OpaqueEndpointInfo,
+    SSLConnectionInfo,
+    SSLEndpointInfo,
+    TCPConnectionInfo,
+    TCPEndpointInfo,
+    UDPConnectionInfo,
+    UDPEndpointInfo,
+    WSConnectionInfo,
+    WSEndpointInfo,
+    intVersion,
+    loadSlice,
+    stringVersion,
+)
+
+__all__ = [
+    "BatchRequest",
+    "Connection",
+    "ConnectionInfo",
+    "Endpoint",
+    "EndpointInfo",
+    "IPConnectionInfo",
+    "IPEndpointInfo",
+    "NativePropertiesAdmin",
+    "OpaqueEndpointInfo",
+    "SSLConnectionInfo",
+    "SSLEndpointInfo",
+    "TCPConnectionInfo",
+    "TCPEndpointInfo",
+    "UDPConnectionInfo",
+    "UDPEndpointInfo",
+    "WSConnectionInfo",
+    "WSEndpointInfo",
+    "intVersion",
+    "loadSlice",
+    "stringVersion",
+]

Ice/Identity.py

@@ -0,0 +1,40 @@
+# 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 Identity:
+    """
+    Represents the identity of an Ice object. It is comparable to the path of a URI. Its string representation is
+    ``name`` when the category is empty, and ``category/name`` when the category is not empty.
+    
+    Attributes
+    ----------
+    name : str
+        The name of the Ice object. An empty name is not valid.
+    category : str
+        The category of the object.
+    
+    Notes
+    -----
+        The Slice compiler generated this dataclass from Slice struct ``::Ice::Identity``.
+    """
+    name: str = ""
+    category: str = ""
+
+_Ice_Identity_t = IcePy.defineStruct(
+    "::Ice::Identity",
+    Identity,
+    (),
+    (
+        ("name", (), IcePy._t_string),
+        ("category", (), IcePy._t_string)
+    ))
+
+__all__ = ["Identity", "_Ice_Identity_t"]

Ice/IdentitySeq.py

@@ -0,0 +1,12 @@
+# Copyright (c) ZeroC, Inc.
+
+# slice2py version 3.8.0
+
+from __future__ import annotations
+import IcePy
+
+from Ice.Identity import _Ice_Identity_t
+
+_Ice_IdentitySeq_t = IcePy.defineSequence("::Ice::IdentitySeq", (), _Ice_Identity_t)
+
+__all__ = ["_Ice_IdentitySeq_t"]

Ice/ImplicitContext.py

@@ -0,0 +1,119 @@
+# Copyright (c) ZeroC, Inc.
+
+from typing import final
+
+import IcePy
+
+
+@final
+class ImplicitContext:
+    """
+    Represents the request context associated with a communicator.
+    When you make a remote invocation without an explicit request context parameter, Ice uses the per-proxy request
+    context (if any) combined with the ``ImplicitContext`` associated with your communicator.
+
+    The property ``Ice.ImplicitContext`` controls if your communicator has an associated implicit context,
+    and when it does, whether this implicit context is per-thread or shared by all threads:
+
+    - None (default):
+        No implicit context at all.
+    - PerThread:
+        The implementation maintains a context per thread.
+    - Shared:
+        The implementation maintains a single context shared by all threads.
+    """
+
+    def __init__(self, impl: IcePy.ImplicitContext):
+        self._impl = impl
+
+    def getContext(self) -> dict[str, str]:
+        """
+        Gets a copy of the request context maintained by this object.
+
+        Returns
+        -------
+        dict[str, str]
+            A copy of the request context.
+        """
+        return self._impl.getContext()
+
+    def setContext(self, newContext: dict[str, str]):
+        """
+        Sets the request context.
+
+        Parameters
+        ----------
+        newContext : dict[str, str]
+            The new request context.
+        """
+        self._impl.setContext(newContext)
+
+    def containsKey(self, key: str) -> bool:
+        """
+        Checks if the specified key has an associated value in the request context.
+
+        Parameters
+        ----------
+        key : str
+            The key.
+
+        Returns
+        -------
+        bool
+            ``True`` if the key has an associated value, ``False`` otherwise.
+        """
+        return self._impl.containsKey(key)
+
+    def get(self, key: str) -> str:
+        """
+        Gets the value associated with the specified key in the request context.
+
+        Parameters
+        ----------
+        key : str
+            The key.
+
+        Returns
+        -------
+        str
+            The value associated with the key, or the empty string if no value is associated with the key.
+            :func:`containsKey` allows you to distinguish between an empty-string value and no value at all.
+        """
+        return self._impl.get(key)
+
+    def put(self, key: str, value: str) -> str | None:
+        """
+        Creates or updates a key/value entry in the request context.
+
+        Parameters
+        ----------
+        key : str
+            The key.
+        value : str
+            The value.
+
+        Returns
+        -------
+        str | None
+            The previous value associated with the key, if any.
+        """
+        return self._impl.put(key, value)
+
+    def remove(self, key: str) -> str | None:
+        """
+        Removes the entry for the specified key in the request context.
+
+        Parameters
+        ----------
+        key : str
+            The key.
+
+        Returns
+        -------
+        str | None
+            The value associated with the key, if any.
+        """
+        return self._impl.remove(key)
+
+
+__all__ = ["ImplicitContext"]

Ice/InitializationData.py

@@ -0,0 +1,65 @@
+# Copyright (c) ZeroC, Inc.
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from .EventLoopAdapter import EventLoopAdapter
+    from .IcePyTypes import BatchRequest, Connection
+    from .Logger import Logger
+    from .Properties import Properties
+    from .UserException import UserException
+    from .Value import Value
+
+
+@dataclass
+class InitializationData:
+    """
+    Represents a set of options that you can specify when initializing a communicator.
+
+    Attributes
+    ----------
+    properties : Ice.Properties | None
+        The properties for the communicator.
+        If not ``None``, this corresponds to the object returned by the :func:`Communicator.getProperties` function.
+    logger : Ice.Logger | None
+        The logger for the communicator.
+    threadStart : Callable[[], None] | None
+        A :class:`Callable` that is invoked whenever the communicator starts a new thread.
+    threadStop : Callable[[], None] | None
+        A :class:`Callable` that is invoked whenever a thread created by the communicator is about to be destroyed.
+    executor : Callable[[Callable[[], None], Connection], None] | None
+        A :class:`Callable` that the communicator invokes to execute dispatches and async invocation callbacks.
+        The callable receives two arguments: a callable and an Ice.Connection object.
+        The executor must eventually invoke the callable with no arguments.
+    batchRequestInterceptor : Callable[[Ice.BatchRequest, int, int], None] | None
+        A :class:`Callable` that is invoked by the Ice runtime to enqueue a batch request.
+        The callable receives three arguments: a BatchRequest object, an integer representing the number of requests
+        currently in the queue, and an integer representing the number of bytes consumed by the requests in the queue.
+        The interceptor must eventually invoke the enqueue function on the BatchRequest object.
+    eventLoopAdapter : Ice.EventLoopAdapter | None
+        An event loop adapter used to run coroutines and wrap futures. If provided, this adapter is responsible for
+        executing coroutines returned by Ice asynchronous dispatch functions and for wrapping Ice futures (from Ice
+        Async APIs) into futures that can be awaited in the application's event loop.
+    sliceLoader : Callable[[str], Ice.Value | Ice.UserException | None] | None
+        A :class:`Callable` used to create instances of Slice classes and user exceptions.
+        Applications can supply a custom slice loader that the Ice runtime will use during unmarshaling.
+        The callable receives one argument: a type ID or compact type ID (as a string) and returns a new instance of the
+        corresponding class or exception, or ``None`` if no such class or exception could be found.
+    """
+
+    properties: Properties | None = None
+    logger: Logger | None = None
+    threadStart: Callable[[], None] | None = None
+    threadStop: Callable[[], None] | None = None
+    executor: Callable[[Callable[[], None], Connection], None] | None = None
+    batchRequestInterceptor: Callable[[BatchRequest, int, int], None] | None = None
+    eventLoopAdapter: EventLoopAdapter | None = None
+    sliceLoader: Callable[[str], Value | UserException | None] | None = None
+
+
+__all__ = ["InitializationData"]

Ice/IntSeq.py

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