Close the gaps in the IcePy stub/module consistency check

python/modules/IcePy/Communicator.cpp

@@ -1566,6 +1566,14 @@ static PyMethodDef CommunicatorMethods[] = {
     {} /* sentinel */
 };
 
+namespace
+{
+    // The constructor signature: a C type documents __init__ on the class, because that is how it
+    // is called. checkIcePyStub.py holds the stub's own __init__ declaration to this line.
+    constexpr const char* IcePy_Communicator_doc =
+        R"(Communicator(initData: Ice.InitializationData | None, /) -> None)";
+}
+
 namespace IcePy
 {
     // clang-format off
@@ -1575,7 +1583,7 @@ namespace IcePy
         .tp_basicsize = sizeof(CommunicatorObject),
         .tp_dealloc = reinterpret_cast<destructor>(communicatorDealloc),
         .tp_flags = Py_TPFLAGS_DEFAULT,
-        .tp_doc = PyDoc_STR("IcePy.Communicator"),
+        .tp_doc = PyDoc_STR(IcePy_Communicator_doc),
         .tp_methods = CommunicatorMethods,
         .tp_init = reinterpret_cast<initproc>(communicatorInit),
         .tp_new = reinterpret_cast<newfunc>(communicatorNew)};

python/modules/IcePy/Operation.cpp

@@ -873,6 +873,16 @@ static PyMethodDef AsyncInvocationContextMethods[] = {
     {} /* sentinel */
 };
 
+namespace
+{
+    // The constructor signature: a C type documents __init__ on the class, because that is how it
+    // is called. checkIcePyStub.py holds the stub's own __init__ declaration to this line.
+    constexpr const char* IcePy_Operation_doc =
+        R"(Operation(sliceName: str, mappedName: str, mode: Ice.OperationMode, format: Ice.FormatType | None, )"
+        R"(metadata: tuple, inParams: tuple, outParams: tuple, returnType: object, exceptions: tuple, )"
+        R"(onewayOnly: bool, /) -> None)";
+}
+
 namespace IcePy
 {
     // clang-format off
@@ -882,7 +892,7 @@ namespace IcePy
         .tp_basicsize = sizeof(OperationObject),
         .tp_dealloc = reinterpret_cast<destructor>(operationDealloc),
         .tp_flags = Py_TPFLAGS_DEFAULT,
-        .tp_doc = PyDoc_STR("IcePy.Operation"),
+        .tp_doc = PyDoc_STR(IcePy_Operation_doc),
         .tp_methods = OperationMethods,
         .tp_init = reinterpret_cast<initproc>(operationInit),
         .tp_new = reinterpret_cast<newfunc>(operationNew),

python/modules/IcePy/Properties.cpp

@@ -745,6 +745,14 @@ static PyMethodDef PropertyMethods[] = {
     {} /* sentinel */
 };
 
+namespace
+{
+    // The constructor signature: a C type documents __init__ on the class, because that is how it
+    // is called. checkIcePyStub.py holds the stub's own __init__ declaration to this line.
+    constexpr const char* IcePy_Properties_doc =
+        R"(Properties(args: list[str] | None = None, defaults: Ice.Properties | None = None, /) -> None)";
+}
+
 namespace IcePy
 {
     // clang-format off
@@ -755,7 +763,7 @@ namespace IcePy
         .tp_dealloc = reinterpret_cast<destructor>(propertiesDealloc),
         .tp_str = reinterpret_cast<reprfunc>(propertiesStr),
         .tp_flags = Py_TPFLAGS_DEFAULT,
-        .tp_doc = PyDoc_STR("IcePy.Properties"),
+        .tp_doc = PyDoc_STR(IcePy_Properties_doc),
         .tp_methods = PropertyMethods,
         .tp_init = reinterpret_cast<initproc>(propertiesInit),
         .tp_new = reinterpret_cast<newfunc>(propertiesNew),

python/modules/IcePy/Proxy.cpp

@@ -1434,6 +1434,14 @@ static PyMethodDef ProxyMethods[] = {
     {} /* sentinel */
 };
 
+namespace
+{
+    // The constructor signature: a C type documents __init__ on the class, because that is how it
+    // is called. checkIcePyStub.py holds the stub's own __init__ declaration to this line.
+    constexpr const char* IcePy_ObjectPrx_doc =
+        R"(ObjectPrx(communicator: Ice.Communicator, proxyString: str, /) -> None)";
+}
+
 namespace IcePy
 {
     // clang-format off
@@ -1445,7 +1453,7 @@ namespace IcePy
         .tp_repr = reinterpret_cast<reprfunc>(proxyRepr),
         .tp_hash = reinterpret_cast<hashfunc>(proxyHash),
         .tp_flags = Py_TPFLAGS_BASETYPE,
-        .tp_doc = PyDoc_STR("IcePy.ObjectPrx"),
+        .tp_doc = PyDoc_STR(IcePy_ObjectPrx_doc),
         .tp_richcompare = reinterpret_cast<richcmpfunc>(proxyCompare),
         .tp_methods = ProxyMethods,
         .tp_init = reinterpret_cast<initproc>(proxyInit),

python/python/IcePy-stubs/__init__.pyi

@@ -715,19 +715,177 @@ class WSEndpointInfo(EndpointInfo):
     resource: str
     """str: The URI configured with the endpoint."""
 
-def stringVersion() -> str: ...
-def intVersion() -> int: ...
-def createProperties(args: list[str] | None = None, defaults: Ice.Properties | None = None, /) -> Properties: ...
-def stringToIdentity(str: str, /) -> Ice.Identity: ...
-def identityToString(identity: Ice.Identity, toStringMode: Ice.ToStringMode | None = None, /) -> str: ...
-def getProcessLogger() -> Ice.Logger | Logger: ...
-def setProcessLogger(logger: Ice.Logger, /) -> None: ...
+def stringVersion() -> str:
+    """
+    Returns the Ice version in the form ``A.B.C``, where ``A`` indicates the major version, ``B`` indicates the
+    minor version, and ``C`` indicates the patch level.
+    For pre-releases, the version includes a pre-release suffix, for example ``3.9.0-alpha.0``.
+
+    Returns
+    -------
+    str
+        The Ice version.
+    """
+    ...
+
+def intVersion() -> int:
+    """
+    Returns the Ice version as an integer in the form ``AABBCC``, where ``AA`` indicates the major version,
+    ``BB`` indicates the minor version, and ``CC`` indicates the patch level.
+    For example, for Ice 3.9.1, the returned value is 30901.
+    For pre-releases, ``CC`` encodes the pre-release; for example, for Ice 3.9.0-alpha.0, the returned value
+    is 30950.
+
+    Returns
+    -------
+    int
+        The Ice version.
+    """
+    ...
+
+def createProperties(args: list[str] | None = None, defaults: Ice.Properties | None = None, /) -> Properties:
+    """
+    Creates a property set initialized from command-line arguments and a default property set.
+
+    Parameters
+    ----------
+    args : list[str] | None, optional
+        The command-line arguments.
+    defaults : Ice.Properties | None, optional
+        Default values for the new property set.
+
+    Returns
+    -------
+    Properties
+        A new property set.
+    """
+    ...
+
+def stringToIdentity(str: str, /) -> Ice.Identity:
+    """
+    Converts a stringified identity into an Identity.
+
+    Parameters
+    ----------
+    str : str
+        The stringified identity.
+
+    Returns
+    -------
+    Ice.Identity
+        An Identity created from the provided string.
+
+    Raises
+    ------
+    ParseException
+        If the string cannot be converted to an object identity.
+    LocalException
+        If the resulting identity has an empty name.
+    """
+    ...
+
+def identityToString(identity: Ice.Identity, toStringMode: Ice.ToStringMode | None = None, /) -> str:
+    """
+    Converts an Identity into a string using the specified mode.
+
+    Parameters
+    ----------
+    identity : Ice.Identity
+        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 stringified identity.
+    """
+    ...
+
+def getProcessLogger() -> Ice.Logger | Logger:
+    """
+    Gets the per-process logger.
+
+    Returns
+    -------
+    Ice.Logger | Logger
+        The current per-process logger instance.
+    """
+    ...
+
+def setProcessLogger(logger: Ice.Logger, /) -> None:
+    """
+    Sets the per-process logger. Communicators created after this call use this logger unless a logger is set
+    in InitializationData or configured through logger properties such as Ice.LogFile.
+
+    Parameters
+    ----------
+    logger : Ice.Logger
+        The new per-process logger instance.
+    """
+    ...
 
 #
 # Functions to load/compile Slice definitions with 'slice2py'.
 #
-def loadSlice(args: list[str], /) -> None: ...
-def compileSlice(args: list[str], /) -> int: ...
+def loadSlice(args: list[str], /) -> None:
+    """
+    Compiles Slice definitions and loads the generated code directly into the current Python environment.
+
+    This function does not generate any Python source files. Instead, the generated Python code is loaded
+    directly into the running interpreter.
+
+    This function does not generate any code for Slice files included by the Slice files being loaded. It is
+    the caller's responsibility to load all necessary Slice definitions. This can be done in a single call to
+    :func:`Ice.loadSlice` by providing all Slice files (including included files) in the `args` parameter, or
+    by making multiple calls to :func:`Ice.loadSlice`.
+
+    When :func:`Ice.loadSlice` is called multiple times with the same Slice file, the corresponding Python
+    code is not reloaded.
+
+    Parameters
+    ----------
+    args : list[str]
+        The list of command-line arguments for the Slice loader. These arguments may include both compiler options and
+        the Slice files to compile.
+
+        Supported compiler options:
+
+            - ``-DNAME``:  Define NAME as 1.
+            - ``-DNAME=DEF``:  Define NAME as DEF.
+            - ``-UNAME``:  Remove any definition for NAME.
+            - ``-IDIR``:  Put DIR in the include file search path.
+            - ``-d``, ``--debug``:  Print debug messages.
+
+    Raises
+    ------
+    RuntimeError
+        If an error occurs during Slice parsing or compilation.
+    """
+    ...
+
+def compileSlice(args: list[str], /) -> int:
+    """
+    Compiles Slice definitions. The behavior is identical to that of the `slice2py` compiler.
+
+    Any errors or warnings emitted during compilation are printed to 'stderr'.
+
+    This is an internal function used in the implementation of the `slice2py` Python script included in the
+    Ice Python package.
+
+    Parameters
+    ----------
+    args : list[str]
+        The list of command-line arguments for Slice compilation, following the same syntax as the `slice2py`
+        compiler.
+
+    Returns
+    -------
+    int
+        The exit code: 0 indicates success, and a non-zero value indicates failure.
+    """
+    ...
 
 #
 # Internal API for IcePy