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

Ice/ServantLocator.py

@@ -8,28 +8,33 @@ from .Object import Object
 
 class ServantLocator(ABC):
     """
-    A servant locator is called by an object adapter to locate a servant that is not found in its active servant map.
+    An application-provided class that an object adapter uses to locate servants.
+
+    Notes
+    -----
+    For simple cases, you should consider using a default servant instead (see :func:`ObjectAdapter.addDefaultServant`).
     """
 
     @abstractmethod
     def locate(self, current: Current) -> tuple[Object | None, object | None]:
         """
-        Called before a request is dispatched if a servant cannot be found in the object adapter's active servant map.
+        Asks this servant locator to find and return a servant.
+
+        Notes
+        -----
+        The caller (the object adapter) does not insert the returned servant into its Active Servant Map.
+        This must be done by the servant locator implementation, if this is desired.
 
-        Note that the object adapter does not automatically insert the returned servant into its active servant map.
-        This must be done by the servant locator implementation, if desired. The `locate` method can throw any user
-        exception. If it does, that exception is marshaled back to the client. If the Slice definition for the corresponding
-        operation includes that user exception, the client receives that user exception; otherwise, the client receives
-        `UnknownUserException`.
+        The implementation can raise any exception, including :class:`UserException`.
+        The Ice runtime will marshal this exception in the response.
 
-        If `locate` throws any exception, the Ice runtime does not call `finished`. If you call `locate` from your own code,
-        you must also call `finished` when you have finished using the servant, provided that `locate` returned a non-null
-        servant.
+        If you call :func:`locate` from your own code, you must also call :func:`finished` when you have finished using
+        the servant, provided that :func:`locate` did not return ``None``.
 
         Parameters
         ----------
         current : Current
-            Information about the current operation for which a servant is required.
+            Information about the incoming request for which a servant is required.
 
         Returns
         -------
@@ -37,55 +42,45 @@ class ServantLocator(ABC):
 
             A tuple containing the following:
                 - retval : Object or None
-                    The located servant, or None if no suitable servant has been found.
+                    The located servant, or ``None`` if no suitable servant was found.
                 - cookie : object | None
-                    A "cookie" that will be passed to `finished`.
-
-        Raises
-        ------
-        UserException
-            The implementation can raise a `UserException` and the runtime will marshal it as the result of the invocation.
+                    A "cookie" that will be passed to :func:`finished`.
         """
         pass
 
     @abstractmethod
     def finished(self, current: Current, servant: Object, cookie: object | None):
         """
-        Called by the object adapter after a request has been made.
+        Notifies this servant locator that the dispatch on the servant returned by :func:`locate` is complete.
+        The object adapter calls this function only when :func:`locate` didn't return ``None``.
 
-        This operation is only called if `locate` was called prior to the request and returned a non-null servant.
-        This operation can be used for cleanup purposes after a request.
+        Notes
+        -----
 
-        The `finished` method can throw any user exception. If it does, that exception is marshaled back to the client.
-        If the Slice definition for the corresponding operation includes that user exception, the client receives that user
-        exception; otherwise, the client receives `UnknownUserException`. If both the operation and `finished` throw an
-        exception, the exception thrown by `finished` is marshaled back to the client.
+        The implementation can raise any exception, including :class:`UserException`.
+        The Ice runtime will marshal this exception in the response. If both the dispatch and :func:`finished` raise
+        an exception, the exception raised by :func:`finished` prevails and is marshaled back to the client.
 
         Parameters
         ----------
         current : Current
-            Information about the current operation call for which a servant was located by `locate`.
+            Information about the incoming request for which a servant was located.
         servant : Object
-            The servant that was returned by `locate`.
+            The servant that was returned by :func:`locate`.
         cookie : object | None
-            The cookie that was returned by `locate`.
-
-        Raises
-        ------
-        UserException
-            The implementation can raise a `UserException` and the runtime will marshal it as the result of the invocation.
+            The cookie that was returned by :func:`locate`.
         """
         pass
 
     @abstractmethod
     def deactivate(self, category: str):
         """
-        Called when the object adapter in which this servant locator is installed is destroyed.
+        Notifies this servant locator that the object adapter in which it's installed is being deactivated.
 
         Parameters
         ----------
         category : str
-            Indicates for which category the servant locator is being deactivated.
+            The category with which this servant locator was registered.
         """
         pass
 

Ice/SliceInfo.py

@@ -3,14 +3,14 @@
 
 class SliceInfo:
     """
-    Encapsulates the details of a slice with an unknown type.
+    Encapsulates the details of a class slice with an unknown type.
 
     Attributes
     ----------
     typeId : str
-        The Slice type ID for this slice.
+        The Slice type ID for this slice. It's empty when ``compactId`` is set (not ``-1``).
     compactId : int
-        The Slice compact type ID for this slice.
+        The Slice compact type ID for this slice, or ``-1`` if the slice has no compact ID.
     bytes : bytes
         The encoded bytes for this slice, including the leading size integer.
     hasOptionalMembers : bool

Ice/SlicedData.py

@@ -8,7 +8,7 @@ class SlicedData:
     Attributes
     ----------
     slices : tuple[SliceInfo, ...]
-        The details of each slice, in order of most-derived to least-derived.
+        The slices of the unknown class, in order of most-derived to least-derived.
     """
 
     pass

Ice/TCPEndpointType.py

@@ -7,5 +7,12 @@ import IcePy
 
 
 TCPEndpointType = 1
+"""
+Identifies TCP endpoints.
+
+Notes
+-----
+    The Slice compiler generated this constant from Slice constant ``::Ice::TCPEndpointType``.
+"""
 
 __all__ = ["TCPEndpointType"]

Ice/ToStringMode.py

@@ -5,30 +5,30 @@ from enum import Enum
 
 class ToStringMode(Enum):
     """
-    The output mode for xxxToString methods such as identityToString and proxyToString. The actual encoding format for
-    the string is the same for all modes: you don't need to specify an encoding format or mode when reading such a
-    string.
-
-    Enumerators:
-
-    - Unicode:
-          Characters with ordinal values greater than 127 are kept as-is in the resulting string. Non-printable ASCII
-          characters with ordinal values 127 and below are encoded as \\t, \\n (etc.) or \\unnnn.
-
-    - ASCII:
-          Characters with ordinal values greater than 127 are encoded as universal character names in the resulting
-          string \\unnnn for BMP characters and \\Unnnnnnnn for non-BMP characters. Non-printable ASCII characters
-          with ordinal values 127 and below are encoded as \\t, \\n (etc.) or \\unnnn.
-
-    - Compat:
-          Characters with ordinal values greater than 127 are encoded as a sequence of UTF-8 bytes using octal escapes.
-          Characters with ordinal values 127 and below are encoded as \\t, \\n (etc.) or an octal escape. Use this mode
-          to generate strings compatible with Ice 3.6 and earlier.
+    The output mode for xxxToString functions such as :func:`identityToString`.
+    The actual encoding format for the string is the same for all modes: you don't need to specify an
+    encoding format or mode when reading such a string.
     """
 
     Unicode = 0
+    """
+    Characters with ordinal values greater than 127 are kept as-is in the resulting string.
+    Non-printable ASCII characters with ordinal values 127 and below are encoded as \\t, \\n (etc.) or \\unnnn.
+    """
+
     ASCII = 1
+    """
+    Characters with ordinal values greater than 127 are encoded as universal character names in the resulting string:
+    \\unnnn for BMP characters and \\Unnnnnnnn for non-BMP characters.
+    Non-printable ASCII characters with ordinal values 127 and below are encoded as \\t, \\n (etc.) or \\unnnn.
+    """
+
     Compat = 2
+    """
+    Characters with ordinal values greater than 127 are encoded as a sequence of UTF-8 bytes using octal escapes.
+    Characters with ordinal values 127 and below are encoded as \\t, \\n (etc.) or an octal escape.
+    Use this mode to generate strings compatible with Ice 3.6 and earlier.
+    """
 
 
 __all__ = ["ToStringMode"]

Ice/UDPEndpointType.py

@@ -7,5 +7,12 @@ import IcePy
 
 
 UDPEndpointType = 3
+"""
+Identifies UDP endpoints.
+
+Notes
+-----
+    The Slice compiler generated this constant from Slice constant ``::Ice::UDPEndpointType``.
+"""
 
 __all__ = ["UDPEndpointType"]

Ice/URIEndpointType.py

@@ -7,5 +7,12 @@ import IcePy
 
 
 URIEndpointType = 0
+"""
+Identifies endpoints marshaled as URI strings.
+
+Notes
+-----
+    The Slice compiler generated this constant from Slice constant ``::Ice::URIEndpointType``.
+"""
 
 __all__ = ["URIEndpointType"]

Ice/UnknownSlicedValue.py

@@ -7,18 +7,26 @@ from .Value import Value
 
 class UnknownSlicedValue(Value):
     """
-    Unknown sliced value holds an instance of an unknown Slice class type.
+    Represents an instance of an unknown class.
 
     Attributes
     ----------
     unknownTypeId : str
-        The type ID of the unknown Slice class type.
+        The Slice type ID of the unknown value.
     """
 
     _ice_type = None  # Will be set after class definition
     unknownTypeId: str
 
-    def ice_id(self):
+    def ice_id(self) -> str:
+        """
+        Returns the Slice type ID associated with this instance.
+
+        Returns
+        -------
+        str
+            The Slice type ID of the unknown value.
+        """
         return self.unknownTypeId
 
 

Ice/UserException.py

@@ -5,7 +5,7 @@ from .Exception import Exception as IceException
 
 class UserException(IceException):
     """
-    The base class for all user-defined exceptions.
+    Base class for all exceptions defined in Slice.
     """
 
     def __str__(self):

Ice/Util.py

@@ -36,18 +36,20 @@ def initialize(
     initData: InitializationData | None = None,
 ) -> Communicator:
     """
-    Creates a new communicator. This function is provided for backwards compatibility. New code should call the
-    :class:`Communicator` constructor directly.
+    Creates a new communicator.
+
+    This function is provided for backwards compatibility.
+    New code should call the :class:`Communicator` constructor directly.
 
     Parameters
     ----------
-    args : list of str, optional
+    args : list[str] | None, optional
         The command-line arguments.
-    eventLoop : asyncio.AbstractEventLoop, optional
-        An asyncio event loop used to run coroutines and wrap futures. This argument and the `initData` argument are
-        mutually exclusive.
-    initData : InitializationData, optional
-        Options for the new communicator. This argument and the `args` argument are mutually exclusive.
+    eventLoop : asyncio.AbstractEventLoop | None, optional
+        An asyncio event loop used to run coroutines and wrap futures.
+    initData : InitializationData | None, optional
+        Options for the new communicator.
+        This argument is mutually exclusive with both the ``args`` and ``eventLoop`` argument.
 
     Returns
     -------
@@ -59,36 +61,37 @@ def initialize(
 
 def identityToString(identity: Identity, toStringMode: ToStringMode | None = None) -> str:
     """
-    Convert an object identity to a string.
+    Converts an Identity into a string using the specified mode.
 
     Parameters
     ----------
     identity : Ice.Identity
-        The object identity to convert.
-    toStringMode : Ice.ToStringMode, optional
-        Specifies if and how non-printable ASCII characters are escaped in the result.
+        The identity.
+    toStringMode : Ice.ToStringMode | None, optional
+        Specifies how to handle non-ASCII characters and non-printable ASCII characters.
+        The default is :const:`Ice.ToStringMode.Unicode`.
 
     Returns
     -------
     str
-        The string representation of the object identity.
+        The stringified identity.
     """
     return IcePy.identityToString(identity, toStringMode)
 
 
 def stringToIdentity(str: str) -> Identity:
     """
-    Convert a string to an object identity.
+    Converts a stringified identity into an Identity.
 
     Parameters
     ----------
     str : str
-        The string to convert.
+        The stringified identity.
 
     Returns
     -------
     Identity
-        The converted object identity.
+        An Identity created from the provided string.
 
     Raises
     ------
@@ -102,14 +105,14 @@ def createProperties(args: list[str] | None = None, defaults: Properties | None
     """
     Creates a property set initialized from command-line arguments and a default property set.
 
-    This function is provided for backwards compatibility. New code should call the :class:`Properties` constructor
-    directly.
+    This function is provided for backwards compatibility.
+    New code should call the :class:`Properties` constructor directly.
 
     Parameters
     ----------
-    args : list[str], optional
+    args : list[str] | None, optional
         The command-line arguments.
-    defaults : Properties, optional
+    defaults : Properties | None, optional
         Default values for the new property set.
 
     Returns
@@ -122,15 +125,13 @@ def createProperties(args: list[str] | None = None, defaults: Properties | None
 
 def getSliceDir() -> str | None:
     """
-    Returns the path to the directory where the Ice Slice files are installed.
-
-    This helper function locates the installation directory for the Ice Slice files,
-    typically used to configure include paths for Slice compilers.
+    This helper function locates the installation directory for the Ice Slice files, and returns its path.
+    This path is typically used to configure include paths for Slice compilers.
 
     Returns
     -------
-    str or None
-        The absolute path to the directory containing the Ice Slice files, or ``None`` if the directory cannot be found.
+    str | None
+        The absolute path of the directory containing the Ice Slice files, or ``None`` if the directory cannot be found.
     """
 
     # Get the parent of the directory containing this file (__init__.py).

Ice/Value.py

@@ -12,12 +12,12 @@ class Value:
 
     def ice_id(self) -> str:
         """
-        Obtain the type ID corresponding to the most-derived Slice interface supported by the target object.
+        Returns the Slice type ID of the most-derived class supported by this object.
 
         Returns
         -------
         str
-            The type ID.
+            The Slice type ID.
         """
         # Call ice_staticId() on self to get the value from the most-derived class.
         return self.ice_staticId()
@@ -25,12 +25,12 @@ class Value:
     @staticmethod
     def ice_staticId() -> str:
         """
-        Obtain the type ID of this Slice class or interface.
+        Returns the Slice type ID of this type.
 
         Returns
         -------
         str
-            The type ID.
+            The return value is always ``::Ice::Object``.
         """
         return "::Ice::Object"
 
@@ -45,13 +45,13 @@ class Value:
 
     def ice_getSlicedData(self) -> SlicedData | None:
         """
-        Return the sliced data if the value has a preserved-slice base class and has been sliced during
-        un-marshaling of the value. Return None otherwise.
+        Gets the sliced data associated with this instance.
 
         Returns
         -------
         SlicedData | None
-            The sliced data or None.
+            If this value has a preserved-slice base class and has been sliced during unmarshaling, this returns the
+            sliced data; otherwise this returns ``None``.
         """
         return getattr(self, "_ice_slicedData", None)
 

Ice/WSEndpointType.py

@@ -7,5 +7,12 @@ import IcePy
 
 
 WSEndpointType = 4
+"""
+Identifies TCP-based WebSocket endpoints.
+
+Notes
+-----
+    The Slice compiler generated this constant from Slice constant ``::Ice::WSEndpointType``.
+"""
 
 __all__ = ["WSEndpointType"]

Ice/WSSEndpointType.py

@@ -7,5 +7,12 @@ import IcePy
 
 
 WSSEndpointType = 5
+"""
+Identifies SSL-based WebSocket endpoints.
+
+Notes
+-----
+    The Slice compiler generated this constant from Slice constant ``::Ice::WSSEndpointType``.
+"""
 
 __all__ = ["WSSEndpointType"]

Ice/__init__.py

@@ -43,6 +43,7 @@ from .IcePyTypes import (
     BatchRequest,
     Connection,
     ConnectionInfo,
+    Endpoint,
     EndpointInfo,
     IPConnectionInfo,
     IPEndpointInfo,
@@ -213,6 +214,7 @@ __all__ = [
     "DatagramLimitException",
     "DispatchException",
     "EncodingVersion",
+    "Endpoint",
     "EndpointInfo",
     "EndpointSelectionType",
     "EventLoopAdapter",

Ice/iAPEndpointType.py

@@ -7,5 +7,12 @@ import IcePy
 
 
 iAPEndpointType = 8
+"""
+Identifies iAP-based endpoints.
+
+Notes
+-----
+    The Slice compiler generated this constant from Slice constant ``::Ice::iAPEndpointType``.
+"""
 
 __all__ = ["iAPEndpointType"]

Ice/iAPSEndpointType.py

@@ -7,5 +7,12 @@ import IcePy
 
 
 iAPSEndpointType = 9
+"""
+Identifies SSL iAP-based endpoints.
+
+Notes
+-----
+    The Slice compiler generated this constant from Slice constant ``::Ice::iAPSEndpointType``.
+"""
 
 __all__ = ["iAPSEndpointType"]

IceGrid/LoadSample.py

@@ -11,25 +11,25 @@ class LoadSample(Enum):
     """
     Determines which load sampling interval to use.
     
-    Enumerators:
-    
-    - LoadSample1:
-        Sample every minute.
-    
-    - LoadSample5:
-        Sample every five minutes.
-    
-    - LoadSample15:
-        Sample every fifteen minutes.
-    
     Notes
     -----
         The Slice compiler generated this enum class from Slice enumeration ``::IceGrid::LoadSample``.
     """
-    
+
     LoadSample1 = 0
+    """
+    Sample every minute.
+    """
+
     LoadSample5 = 1
+    """
+    Sample every five minutes.
+    """
+
     LoadSample15 = 2
+    """
+    Sample every fifteen minutes.
+    """
 
 _IceGrid_LoadSample_t = IcePy.defineEnum(
     "::IceGrid::LoadSample",

IceGrid/ServerState.py

@@ -11,42 +11,46 @@ class ServerState(Enum):
     """
     Represents the state of a server.
     
-    Enumerators:
-    
-    - Inactive:
-        The server is not running.
-    
-    - Activating:
-        The server is being activated and will change to the active state when the registered server object adapters
-        are activated or to the activation timed out state if the activation timeout expires.
-    
-    - ActivationTimedOut:
-        The server activation timed out.
-    
-    - Active:
-        The server is running.
-    
-    - Deactivating:
-        The server is being deactivated.
-    
-    - Destroying:
-        The server is being destroyed.
-    
-    - Destroyed:
-        The server is destroyed.
-    
     Notes
     -----
         The Slice compiler generated this enum class from Slice enumeration ``::IceGrid::ServerState``.
     """
-    
+
     Inactive = 0
+    """
+    The server is not running.
+    """
+
     Activating = 1
+    """
+    The server is being activated and will change to the active state when the registered server object adapters
+    are activated or to the activation timed out state if the activation timeout expires.
+    """
+
     ActivationTimedOut = 2
+    """
+    The server activation timed out.
+    """
+
     Active = 3
+    """
+    The server is running.
+    """
+
     Deactivating = 4
+    """
+    The server is being deactivated.
+    """
+
     Destroying = 5
+    """
+    The server is being destroyed.
+    """
+
     Destroyed = 6
+    """
+    The server is destroyed.
+    """
 
 _IceGrid_ServerState_t = IcePy.defineEnum(
     "::IceGrid::ServerState",