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

Ice/Current.py

@@ -2,9 +2,8 @@
 
 from dataclasses import dataclass
 
-from IcePy import Connection
-
 from .EncodingVersion import EncodingVersion
+from .IcePyTypes import Connection
 from .Identity import Identity
 from .ObjectAdapter import ObjectAdapter
 from .OperationMode import OperationMode
@@ -19,8 +18,8 @@ class Current:
     ----------
     adapter : Ice.ObjectAdapter
         The object adapter that received the request.
-    con : IcePy.Connection | None
-        The connection that received the request. It's None when the invocation and dispatch are collocated.
+    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
@@ -32,9 +31,9 @@ class Current:
     ctx : dict[str, str]
         The request context.
     requestId : int
-        The request ID. 0 means the request is a one-way request.
+        The request ID. ``0`` means the request is one-way.
     encoding : Ice.EncodingVersion
-        The encoding of the request payload.
+        The Slice encoding version used to marshal the payload of the request.
     """
 
     adapter: ObjectAdapter

Ice/EndpointSelectionType.py

@@ -5,18 +5,18 @@ 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.
+    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

@@ -18,8 +18,8 @@ class EventLoopAdapter(ABC):
     @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.
+        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
         ----------
@@ -36,8 +36,8 @@ class EventLoopAdapter(ABC):
     @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.
+        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
         ----------

Ice/Exception.py

@@ -5,23 +5,21 @@ from builtins import Exception as BuiltinsException
 
 class Exception(BuiltinsException):
     """
-    The base class for all Ice exceptions.
+    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):
+    def ice_id(self) -> str:
         """
-        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 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 the exception.
+            The type ID of this exception.
         """
         return self._ice_id
 

Ice/FormatType.py

@@ -5,11 +5,18 @@ from enum import Enum
 
 class FormatType(Enum):
     """
-    This enumeration describes the possible formats for classes and exceptions.
+    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"]

Ice/Future.py

@@ -31,17 +31,16 @@ class Future(Awaitable[_T]):
             yield self
         return self.result()
 
-    def cancel(self):
+    def cancel(self) -> bool:
         """
-        Attempt to cancel the operation.
+        Attempts to cancel this future.
 
-        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.
+        If this future is already running or has completed, it cannot be cancelled.
 
         Returns
         -------
         bool
-            True if the operation was cancelled, False otherwise.
+            ``True`` if this future was cancelled, ``False`` otherwise.
         """
         callbacks = []
         with self._condition:
@@ -60,57 +59,52 @@ class Future(Awaitable[_T]):
 
         return True
 
-    def cancelled(self):
+    def cancelled(self) -> bool:
         """
-        Check if the future has been cancelled.
+        Checks if this future has been cancelled.
 
         Returns
         -------
         bool
-            True if the future was cancelled using `cancel()`, otherwise False.
+            ``True`` if this future was cancelled, otherwise ``False``.
         """
         with self._condition:
             return self._state == Future.StateCancelled
 
-    def running(self):
+    def running(self) -> bool:
         """
-        Check if the future is still running.
+        Checks if this future is still running.
 
         Returns
         -------
         bool
-            True if the operation is currently executing and cannot be cancelled,
-            otherwise False.
+            ``True`` if this future is currently executing, otherwise ``False``.
         """
         with self._condition:
             return self._state == Future.StateRunning
 
-    def done(self):
+    def done(self) -> bool:
         """
-        Check if the future has completed or been cancelled.
+        Checks if this 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.
+            ``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) -> None:
+    def add_done_callback(self, fn: Callable[["Future"], Any]) -> 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.
+        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
-            The function to execute upon completion. Takes the future as its argument.
+        fn : Callable[[Future], Any]
+            The function to execute upon completion.
         """
         with self._condition:
             if self._state == Future.StateRunning:
@@ -120,20 +114,16 @@ class Future(Awaitable[_T]):
 
     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.
+        Retrieves the result of this future's operation.
 
-        If the future was cancelled before completing, an `InvocationCanceledException` is raised.
-
-        If the operation raised an exception, this method raises the same exception.
+        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, optional
-            Maximum time (in seconds) to wait for the result. If `None`, the method waits indefinitely until the
-            operation completes.
+        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
         -------
@@ -164,25 +154,20 @@ class Future(Awaitable[_T]):
 
     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.
+        Retrieves the exception raised by this future's operation.
 
-        If the future was cancelled before completing, an `InvocationCanceledException` is raised.
-
-        If the operation completed successfully without raising an exception, `None` is returned.
+        If the operation has not completed, this function will wait up to ``timeout``-many seconds for it to finish.
 
         Parameters
         ----------
-        timeout : int | float, optional
-            Maximum time (in seconds) to wait for the exception. If `None`, the method waits indefinitely until the
-            operation completes.
+        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 or None
-            The exception raised by the operation, or `None` if the operation completed successfully.
+        BaseException | None
+            The exception raised by the operation, or ``None`` if the operation completed successfully.
 
         Raises
         ------
@@ -201,12 +186,12 @@ class Future(Awaitable[_T]):
 
     def set_result(self, result: _T):
         """
-        Set the result of the future and mark it as completed.
+        Sets the result of this future and marks 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.
+        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 method has no effect.
+        If the future is not in a running state, this function has no effect.
 
         Parameters
         ----------
@@ -227,12 +212,12 @@ class Future(Awaitable[_T]):
 
     def set_exception(self, ex: BaseException):
         """
-        Set an exception for the future and mark it as completed.
+        Sets an exception for this future and marks 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.
+        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 method has no effect.
+        If the future is not in a running state, this function has no effect.
 
         Parameters
         ----------
@@ -286,34 +271,33 @@ class Future(Awaitable[_T]):
 
 def wrap_future(future: Future | asyncio.Future, *, loop: asyncio.AbstractEventLoop | None = None) -> asyncio.Future:
     """
-    Wrap an :class:`Ice.Future` object into an ``asyncio.Future``.
+    Wraps 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
+    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.
+    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.
+    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 Ice.Future object to wrap. If an asyncio.Future is passed, it is returned as-is.
+        The 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.
+    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 input Ice.Future.
+        A future that mirrors the state of the provided :class:`Ice.Future`.
 
     Raises
     ------
     AssertionError
-        If `future` is not an instance of Ice.Future or asyncio.Future.
+        If ``future`` is not an instance of :class:`Ice.Future` or ``asyncio.Future``.
     """
 
     if isinstance(future, asyncio.Future):
@@ -342,7 +326,7 @@ def wrap_future(future: Future | asyncio.Future, *, loop: asyncio.AbstractEventL
 
     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.
+        # 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))
@@ -352,23 +336,39 @@ def wrap_future(future: Future | asyncio.Future, *, loop: asyncio.AbstractEventL
 
 
 class FutureLike(Protocol[_T_co]):
-    """A protocol that defines the interface for objects that behave like a Future."""
+    """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:
-        """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).
+        """
+        Adds a callback to be run when the ``Future`` is done.
 
-        Note: Using positional-only parameter (/) to match both asyncio and
-            concurrent.futures implementations regardless of parameter name.
+        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:
-        """Return the result of the Future."""
+        """
+        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``.
+        """
         ...
 
 

Ice/IcePyTypes.py

@@ -6,6 +6,7 @@ from IcePy import (
     BatchRequest,
     Connection,
     ConnectionInfo,
+    Endpoint,
     EndpointInfo,
     IPConnectionInfo,
     IPEndpointInfo,
@@ -28,6 +29,7 @@ __all__ = [
     "BatchRequest",
     "Connection",
     "ConnectionInfo",
+    "Endpoint",
     "EndpointInfo",
     "IPConnectionInfo",
     "IPEndpointInfo",

Ice/ImplicitContext.py

@@ -8,24 +8,19 @@ import IcePy
 @final
 class ImplicitContext:
     """
-    An interface to associate implicit contexts with communicators.
+    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.
 
-    When you make a remote invocation without an explicit context parameter, Ice uses the per-proxy context (if any)
-    combined with the ImplicitContext associated with the 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:
 
-    Ice provides several implementations of ImplicitContext. The implementation used depends on the value of the
-    `Ice.ImplicitContext` property.
-
-    None (default)
+    - None (default):
         No implicit context at all.
-    PerThread
+    - PerThread:
         The implementation maintains a context per thread.
-    Shared
+    - Shared:
         The implementation maintains a single context shared by all threads.
-
-
-    ImplicitContext also provides a number of operations to create, update, or retrieve an entry in the underlying
-    context without first retrieving a copy of the entire context.
     """
 
     def __init__(self, impl: IcePy.ImplicitContext):
@@ -33,92 +28,90 @@ class ImplicitContext:
 
     def getContext(self) -> dict[str, str]:
         """
-        Get a copy of the underlying context.
+        Gets a copy of the request context maintained by this object.
 
         Returns
         -------
-        dict
-            A copy of the underlying context.
+        dict[str, str]
+            A copy of the request context.
         """
         return self._impl.getContext()
 
     def setContext(self, newContext: dict[str, str]):
         """
-        Set the underlying context.
+        Sets the request context.
 
         Parameters
         ----------
-        newContext : dict
-            The new context to set.
+        newContext : dict[str, str]
+            The new request context.
         """
         self._impl.setContext(newContext)
 
     def containsKey(self, key: str) -> bool:
         """
-        Check if this key has an associated value in the underlying context.
+        Checks if the specified key has an associated value in the request context.
 
         Parameters
         ----------
         key : str
-            The key to check.
+            The key.
 
         Returns
         -------
         bool
-            True if the key has an associated value, False otherwise.
+            ``True`` if the key has an associated value, ``False`` otherwise.
         """
         return self._impl.containsKey(key)
 
     def get(self, key: str) -> str:
         """
-        Get the value associated with the given key in the underlying context.
-
-        Returns an empty string if no value is associated with the key. Use `containsKey` to distinguish between an
-        empty-string value and no value at all.
+        Gets the value associated with the specified key in the request context.
 
         Parameters
         ----------
         key : str
-            The key to retrieve the value for.
+            The key.
 
         Returns
         -------
         str
-            The value associated with the key, or an empty string if no value is associated with the key.
+            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:
         """
-        Create or update a key/value entry in the underlying context.
+        Creates or updates a key/value entry in the request context.
 
         Parameters
         ----------
         key : str
-            The key to create or update.
+            The key.
         value : str
-            The value to associate with the key.
+            The value.
 
         Returns
         -------
         str | None
-            The previous value associated with the key, if any, otherwise None.
+            The previous value associated with the key, if any.
         """
         return self._impl.put(key, value)
 
     def remove(self, key: str) -> str | None:
         """
-        Remove the entry for the given key in the underlying context.
+        Removes the entry for the specified key in the request context.
 
         Parameters
         ----------
         key : str
-            The key to remove.
+            The key.
 
         Returns
         -------
         str | None
-            The value associated with the key, if any, otherwise None.
+            The value associated with the key, if any.
         """
         return self._impl.remove(key)