From f7f713d896adc8f09dd14b6c7069c67328f2b156 Mon Sep 17 00:00:00 2001 From: Joe George Date: Tue, 1 Sep 2026 15:38:33 -0400 Subject: [PATCH] Generate IcePy docstrings from the stub The stub is the single source for IcePy docstrings: generateIcePyDocs.py renders it into the committed DocStrings.h, and CI verifies the header is current. --- .github/workflows/python.yml | 10 +- .../modules/IcePy/BatchRequestInterceptor.cpp | 58 +- python/modules/IcePy/Communicator.cpp | 75 +- python/modules/IcePy/Connection.cpp | 216 +---- python/modules/IcePy/ConnectionInfo.cpp | 47 +- python/modules/IcePy/DocStrings.h | 872 ++++++++++++++++++ python/modules/IcePy/Endpoint.cpp | 32 +- python/modules/IcePy/EndpointInfo.cpp | 83 +- python/modules/IcePy/Executor.cpp | 2 + python/modules/IcePy/ImplicitContext.cpp | 18 +- python/modules/IcePy/Init.cpp | 200 +--- python/modules/IcePy/Logger.cpp | 21 +- python/modules/IcePy/ObjectAdapter.cpp | 86 +- python/modules/IcePy/Operation.cpp | 25 +- python/modules/IcePy/Properties.cpp | 35 +- python/modules/IcePy/PropertiesAdmin.cpp | 30 +- python/modules/IcePy/Proxy.cpp | 139 +-- python/modules/IcePy/Types.cpp | 5 +- python/modules/IcePy/msbuild/icepy.vcxproj | 1 + python/python/IcePy-stubs/__init__.pyi | 191 +++- scripts/README.md | 18 + scripts/checkIcePyStub.py | 144 --- scripts/generateIcePyDocs.py | 222 +++++ 23 files changed, 1620 insertions(+), 910 deletions(-) create mode 100644 python/modules/IcePy/DocStrings.h create mode 100644 scripts/README.md delete mode 100644 scripts/checkIcePyStub.py create mode 100644 scripts/generateIcePyDocs.py diff --git a/.github/workflows/python.yml b/.github/workflows/python.yml index b50728eb671..dcb7964ec6d 100644 --- a/.github/workflows/python.yml +++ b/.github/workflows/python.yml @@ -50,6 +50,11 @@ jobs: working-directory: python run: uv sync --group dev + - name: Check the generated IcePy docstring header + working-directory: python + run: | + uv run python ../scripts/generateIcePyDocs.py --check + - name: Build Ice for Python run: | make -C cpp srcs @@ -61,8 +66,3 @@ jobs: working-directory: python run: | uv run pyright --project .. - - - name: Check the IcePy stub against the IcePy module - working-directory: python - run: | - PYTHONPATH=python uv run python ../scripts/checkIcePyStub.py diff --git a/python/modules/IcePy/BatchRequestInterceptor.cpp b/python/modules/IcePy/BatchRequestInterceptor.cpp index b9790037dad..2402b662888 100644 --- a/python/modules/IcePy/BatchRequestInterceptor.cpp +++ b/python/modules/IcePy/BatchRequestInterceptor.cpp @@ -1,50 +1,13 @@ // Copyright (c) ZeroC, Inc. #include "BatchRequestInterceptor.h" +#include "DocStrings.h" #include "Proxy.h" #include "Thread.h" using namespace std; using namespace IcePy; -namespace -{ - constexpr const char* batchRequestGetSize_doc = R"(getSize() -> int - -Gets the size of the request. - -Returns -------- -int - The number of bytes consumed by the request.)"; - - constexpr const char* batchRequestGetOperation_doc = R"(getOperation() -> str - -Gets the name of the operation. - -Returns -------- -str - The operation name.)"; - - constexpr const char* batchRequestGetProxy_doc = R"(getProxy() -> Ice.ObjectPrx - -Gets the proxy used to create this batch request. - -Returns -------- -Ice.ObjectPrx - The proxy.)"; - - constexpr const char* batchRequestEnqueue_doc = R"(enqueue() -> None - -Queues this request.)"; - - constexpr const char* BatchRequestType_doc = - R"(Represents a batch request. -A batch request is created by invoking an operation on a batch-oneway or batch-datagram proxy.)"; -} - namespace IcePy { struct BatchRequestObject @@ -158,13 +121,22 @@ batchRequestEnqueue(BatchRequestObject* self, PyObject* /*args*/) } static PyMethodDef BatchRequestMethods[] = { - {"getSize", reinterpret_cast(batchRequestGetSize), METH_NOARGS, PyDoc_STR(batchRequestGetSize_doc)}, + {"getSize", + reinterpret_cast(batchRequestGetSize), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_BatchRequest_getSize)}, {"getOperation", reinterpret_cast(batchRequestGetOperation), METH_NOARGS, - PyDoc_STR(batchRequestGetOperation_doc)}, - {"getProxy", reinterpret_cast(batchRequestGetProxy), METH_NOARGS, PyDoc_STR(batchRequestGetProxy_doc)}, - {"enqueue", reinterpret_cast(batchRequestEnqueue), METH_NOARGS, PyDoc_STR(batchRequestEnqueue_doc)}, + PyDoc_STR(IcePy_DOC_BatchRequest_getOperation)}, + {"getProxy", + reinterpret_cast(batchRequestGetProxy), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_BatchRequest_getProxy)}, + {"enqueue", + reinterpret_cast(batchRequestEnqueue), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_BatchRequest_enqueue)}, {} /* sentinel */ }; @@ -177,7 +149,7 @@ namespace IcePy .tp_basicsize = sizeof(BatchRequestObject), .tp_dealloc = (destructor)batchRequestDealloc, .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = PyDoc_STR(BatchRequestType_doc), + .tp_doc = PyDoc_STR(IcePy_DOC_BatchRequest), .tp_methods = BatchRequestMethods, .tp_new = (newfunc)batchRequestNew, }; diff --git a/python/modules/IcePy/Communicator.cpp b/python/modules/IcePy/Communicator.cpp index 732d7b66adf..809dfc0f153 100644 --- a/python/modules/IcePy/Communicator.cpp +++ b/python/modules/IcePy/Communicator.cpp @@ -3,6 +3,7 @@ #include "Communicator.h" #include "BatchRequestInterceptor.h" #include "DefaultSliceLoader.h" +#include "DocStrings.h" #include "Executor.h" #include "Future.h" #include "Ice/DisableWarnings.h" @@ -1437,132 +1438,138 @@ communicatorSetDefaultLocator(CommunicatorObject* self, PyObject* args) } static PyMethodDef CommunicatorMethods[] = { - {"destroy", reinterpret_cast(communicatorDestroy), METH_NOARGS, PyDoc_STR("destroy() -> None")}, + {"destroy", + reinterpret_cast(communicatorDestroy), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_Communicator_destroy)}, {"destroyAsync", reinterpret_cast(communicatorDestroyAsync), METH_VARARGS, - PyDoc_STR("destroyAsync(callable: Callable, /) -> None")}, - {"shutdown", reinterpret_cast(communicatorShutdown), METH_NOARGS, PyDoc_STR("shutdown() -> None")}, + PyDoc_STR(IcePy_DOC_Communicator_destroyAsync)}, + {"shutdown", + reinterpret_cast(communicatorShutdown), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_Communicator_shutdown)}, {"waitForShutdown", reinterpret_cast(communicatorWaitForShutdown), METH_VARARGS, - PyDoc_STR("waitForShutdown(timeout: int, /) -> bool")}, + PyDoc_STR(IcePy_DOC_Communicator_waitForShutdown)}, {"shutdownCompleted", reinterpret_cast(communicatorShutdownCompleted), METH_NOARGS, - PyDoc_STR("shutdownCompleted() -> Awaitable[None]")}, + PyDoc_STR(IcePy_DOC_Communicator_shutdownCompleted)}, {"isShutdown", reinterpret_cast(communicatorIsShutdown), METH_NOARGS, - PyDoc_STR("isShutdown() -> bool")}, + PyDoc_STR(IcePy_DOC_Communicator_isShutdown)}, {"stringToProxy", reinterpret_cast(communicatorStringToProxy), METH_VARARGS, - PyDoc_STR("stringToProxy(str: str, /) -> Ice.ObjectPrx | None")}, + PyDoc_STR(IcePy_DOC_Communicator_stringToProxy)}, {"proxyToString", reinterpret_cast(communicatorProxyToString), METH_VARARGS, - PyDoc_STR("proxyToString(proxy: Ice.ObjectPrx | None, /) -> str")}, + PyDoc_STR(IcePy_DOC_Communicator_proxyToString)}, {"propertyToProxy", reinterpret_cast(communicatorPropertyToProxy), METH_VARARGS, - PyDoc_STR("propertyToProxy(property: str, /) -> Ice.ObjectPrx | None")}, + PyDoc_STR(IcePy_DOC_Communicator_propertyToProxy)}, {"proxyToProperty", reinterpret_cast(communicatorProxyToProperty), METH_VARARGS, - PyDoc_STR("proxyToProperty(proxy: Ice.ObjectPrx, property: str, /) -> dict[str, str]")}, + PyDoc_STR(IcePy_DOC_Communicator_proxyToProperty)}, {"identityToString", reinterpret_cast(communicatorIdentityToString), METH_VARARGS, - PyDoc_STR("identityToString(identity: Ice.Identity, /) -> str")}, + PyDoc_STR(IcePy_DOC_Communicator_identityToString)}, {"createObjectAdapter", reinterpret_cast(communicatorCreateObjectAdapter), METH_VARARGS, - PyDoc_STR("createObjectAdapter(name: str, /) -> ObjectAdapter")}, + PyDoc_STR(IcePy_DOC_Communicator_createObjectAdapter)}, {"createObjectAdapterWithEndpoints", reinterpret_cast(communicatorCreateObjectAdapterWithEndpoints), METH_VARARGS, - PyDoc_STR("createObjectAdapterWithEndpoints(name: str, endpoints: str, /) -> ObjectAdapter")}, + PyDoc_STR(IcePy_DOC_Communicator_createObjectAdapterWithEndpoints)}, {"createObjectAdapterWithRouter", reinterpret_cast(communicatorCreateObjectAdapterWithRouter), METH_VARARGS, - PyDoc_STR("createObjectAdapterWithRouter(name: str, router: Ice.RouterPrx, /) -> ObjectAdapter")}, + PyDoc_STR(IcePy_DOC_Communicator_createObjectAdapterWithRouter)}, {"getDefaultObjectAdapter", reinterpret_cast(communicatorGetDefaultObjectAdapter), METH_NOARGS, - PyDoc_STR("getDefaultObjectAdapter() -> Ice.ObjectAdapter | None")}, + PyDoc_STR(IcePy_DOC_Communicator_getDefaultObjectAdapter)}, {"setDefaultObjectAdapter", reinterpret_cast(communicatorSetDefaultObjectAdapter), METH_VARARGS, - PyDoc_STR("setDefaultObjectAdapter(adapter: Ice.ObjectAdapter | None, /) -> None")}, + PyDoc_STR(IcePy_DOC_Communicator_setDefaultObjectAdapter)}, {"getImplicitContext", reinterpret_cast(communicatorGetImplicitContext), METH_NOARGS, - PyDoc_STR("getImplicitContext() -> ImplicitContext | None")}, + PyDoc_STR(IcePy_DOC_Communicator_getImplicitContext)}, {"getProperties", reinterpret_cast(communicatorGetProperties), METH_NOARGS, - PyDoc_STR("getProperties() -> Properties")}, + PyDoc_STR(IcePy_DOC_Communicator_getProperties)}, {"getLogger", reinterpret_cast(communicatorGetLogger), METH_NOARGS, - PyDoc_STR("getLogger() -> Ice.Logger | Logger")}, + PyDoc_STR(IcePy_DOC_Communicator_getLogger)}, {"getDefaultRouter", reinterpret_cast(communicatorGetDefaultRouter), METH_NOARGS, - PyDoc_STR("getDefaultRouter() -> Ice.RouterPrx | None")}, + PyDoc_STR(IcePy_DOC_Communicator_getDefaultRouter)}, {"setDefaultRouter", reinterpret_cast(communicatorSetDefaultRouter), METH_VARARGS, - PyDoc_STR("setDefaultRouter(router: Ice.RouterPrx | None, /) -> None")}, + PyDoc_STR(IcePy_DOC_Communicator_setDefaultRouter)}, {"getDefaultLocator", reinterpret_cast(communicatorGetDefaultLocator), METH_NOARGS, - PyDoc_STR("getDefaultLocator() -> Ice.LocatorPrx | None")}, + PyDoc_STR(IcePy_DOC_Communicator_getDefaultLocator)}, {"setDefaultLocator", reinterpret_cast(communicatorSetDefaultLocator), METH_VARARGS, - PyDoc_STR("setDefaultLocator(locator: Ice.LocatorPrx | None, /) -> None")}, + PyDoc_STR(IcePy_DOC_Communicator_setDefaultLocator)}, {"flushBatchRequests", reinterpret_cast(communicatorFlushBatchRequests), METH_VARARGS, - PyDoc_STR("flushBatchRequests(compress: Ice.CompressBatch, /) -> None")}, + PyDoc_STR(IcePy_DOC_Communicator_flushBatchRequests)}, {"flushBatchRequestsAsync", reinterpret_cast(communicatorFlushBatchRequestsAsync), METH_VARARGS, - PyDoc_STR("flushBatchRequestsAsync(compress: Ice.CompressBatch, /) -> Awaitable[None]")}, + PyDoc_STR(IcePy_DOC_Communicator_flushBatchRequestsAsync)}, {"createAdmin", reinterpret_cast(communicatorCreateAdmin), METH_VARARGS, - PyDoc_STR("createAdmin(adminAdapter: Ice.ObjectAdapter | None, adminIdentity: Ice.Identity, /) -> Ice.ObjectPrx")}, + PyDoc_STR(IcePy_DOC_Communicator_createAdmin)}, {"getAdmin", reinterpret_cast(communicatorGetAdmin), METH_NOARGS, - PyDoc_STR("getAdmin() -> Ice.ObjectPrx | None")}, + PyDoc_STR(IcePy_DOC_Communicator_getAdmin)}, {"addAdminFacet", reinterpret_cast(communicatorAddAdminFacet), METH_VARARGS, - PyDoc_STR("addAdminFacet(servant: Ice.Object, facet: str, /) -> None")}, + PyDoc_STR(IcePy_DOC_Communicator_addAdminFacet)}, {"findAdminFacet", reinterpret_cast(communicatorFindAdminFacet), METH_VARARGS, - PyDoc_STR("findAdminFacet(facet: str, /) -> Ice.Object | NativePropertiesAdmin | None")}, + PyDoc_STR(IcePy_DOC_Communicator_findAdminFacet)}, {"findAllAdminFacets", reinterpret_cast(communicatorFindAllAdminFacets), METH_NOARGS, - PyDoc_STR("findAllAdminFacets() -> dict[str, Ice.Object | NativePropertiesAdmin]")}, + PyDoc_STR(IcePy_DOC_Communicator_findAllAdminFacets)}, {"removeAdminFacet", reinterpret_cast(communicatorRemoveAdminFacet), METH_VARARGS, - PyDoc_STR("removeAdminFacet(facet: str, /) -> Ice.Object | None")}, + PyDoc_STR(IcePy_DOC_Communicator_removeAdminFacet)}, {"_setWrapper", reinterpret_cast(communicatorSetWrapper), METH_VARARGS, - PyDoc_STR("_setWrapper(wrapper: Ice.Communicator, /) -> None")}, + PyDoc_STR(IcePy_DOC_Communicator__setWrapper)}, {"_getWrapper", reinterpret_cast(communicatorGetWrapper), METH_NOARGS, - PyDoc_STR("_getWrapper() -> Ice.Communicator")}, + PyDoc_STR(IcePy_DOC_Communicator__getWrapper)}, {} /* sentinel */ }; @@ -1575,7 +1582,7 @@ namespace IcePy .tp_basicsize = sizeof(CommunicatorObject), .tp_dealloc = reinterpret_cast(communicatorDealloc), .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = PyDoc_STR("IcePy.Communicator"), + .tp_doc = PyDoc_STR(IcePy_DOC_Communicator), .tp_methods = CommunicatorMethods, .tp_init = reinterpret_cast(communicatorInit), .tp_new = reinterpret_cast(communicatorNew)}; diff --git a/python/modules/IcePy/Connection.cpp b/python/modules/IcePy/Connection.cpp index ce3c18bf725..7d59ff59817 100644 --- a/python/modules/IcePy/Connection.cpp +++ b/python/modules/IcePy/Connection.cpp @@ -3,6 +3,7 @@ #include "Connection.h" #include "Communicator.h" #include "ConnectionInfo.h" +#include "DocStrings.h" #include "Endpoint.h" #include "Future.h" #include "ObjectAdapter.h" @@ -53,186 +54,6 @@ namespace }; long hashPointer(void* ptr) { return Hasher()(ptr); } - - constexpr const char* connectionAbort_doc = R"(abort() -> None - -Aborts this connection.)"; - - constexpr const char* connectionClose_doc = R"(close() -> Awaitable[None] - -Starts a graceful closure of this connection once all outstanding invocations have completed. - -Returns -------- -Awaitable[None] - A future that becomes available when the connection is closed. If the connection was lost or - aborted, awaiting this future raises the exception that caused the connection's closure.)"; - - constexpr const char* connectionCreateProxy_doc = R"(createProxy(identity: Ice.Identity, /) -> Ice.ObjectPrx - -Creates a special proxy (a 'fixed proxy') that always uses this connection. - -Parameters ----------- -identity : Ice.Identity - The identity of the target object. - -Returns -------- -Ice.ObjectPrx - A fixed proxy with the provided identity. - -Raises ------- -CommunicatorDestroyedException - If the communicator has been destroyed.)"; - - constexpr const char* connectionDisableInactivityCheck_doc = R"(disableInactivityCheck() -> None - -Disables the inactivity check on this connection. - -By default, Ice will close connections that remain inactive for a certain period. -This method disables that behavior for this connection.)"; - - constexpr const char* connectionSetAdapter_doc = R"(setAdapter(adapter: Ice.ObjectAdapter | None, /) -> None - -Associates an object adapter with this connection. - -When a connection receives a request, it dispatches this request using its associated object adapter. -If the associated object adapter is ``None``, the connection rejects any incoming request with an -:class:`Ice.ObjectNotExistException`. - -The default object adapter of an incoming connection is the object adapter that created this connection; -the default object adapter of an outgoing connection is the communicator's default object adapter. - -Parameters ----------- -adapter : Ice.ObjectAdapter | None - The object adapter to associate with this connection. - -Raises ------- -LocalException - If this connection is an incoming (server) connection: only outgoing (client) connections - support setting the object adapter.)"; - - constexpr const char* connectionGetAdapter_doc = R"(getAdapter() -> Ice.ObjectAdapter | None - -Gets the object adapter associated with this connection. - -Returns -------- -Ice.ObjectAdapter | None - The object adapter associated with this connection.)"; - - constexpr const char* connectionFlushBatchRequests_doc = - R"(flushBatchRequests(compress: Ice.CompressBatch, /) -> None - -Flushes any pending batch requests for this connection. - -This corresponds to all batch requests invoked on fixed proxies associated with the connection. - -Parameters ----------- -compress : Ice.CompressBatch - Specifies whether or not the queued batch requests should be compressed before being sent over the wire. - -Raises ------- -LocalException - If the flush fails. For example, this method raises CommunicatorDestroyedException if the communicator - has been destroyed.)"; - - constexpr const char* connectionFlushBatchRequestsAsync_doc = - R"(flushBatchRequestsAsync(compress: Ice.CompressBatch, /) -> Awaitable[None] - -Flushes any pending batch requests for this connection asynchronously. - -This corresponds to all batch requests invoked on fixed proxies associated with the connection. - -Parameters ----------- -compress : Ice.CompressBatch - Specifies whether or not the queued batch requests should be compressed before being sent over the wire. - -Returns -------- -Awaitable[None] - A future that becomes available when the flush completes. - -Raises ------- -CommunicatorDestroyedException - If the communicator has been destroyed. This exception is raised synchronously.)"; - - constexpr const char* connectionSetCloseCallback_doc = - R"(setCloseCallback(callback: Callable[[Connection], None] | None, /) -> None - -Sets a close callback on the connection. The callback is called by the connection when it's closed. -The callback is called from the Ice thread pool associated with the connection. - -Parameters ----------- -callback : Callable[[Connection], None] | None - The close callback callable, or ``None`` to remove the current callback.)"; - - constexpr const char* connectionType_doc = R"(type() -> str - -Returns the connection type. This corresponds to the endpoint type, such as 'tcp', 'udp', etc. - -Returns -------- -str - The type of the connection.)"; - - constexpr const char* connectionToString_doc = R"(toString() -> str - -Returns a description of the connection as human readable text, suitable for logging or error messages. - -Notes ------ -This method remains usable after the connection is closed or aborted. - -Returns -------- -str - The description of the connection as human readable text.)"; - - constexpr const char* connectionGetInfo_doc = R"(getInfo() -> Ice.ConnectionInfo - -Returns the connection information. - -Returns -------- -Ice.ConnectionInfo - The connection information.)"; - - constexpr const char* connectionGetEndpoint_doc = R"(getEndpoint() -> Ice.Endpoint - -Gets the endpoint from which the connection was created. - -Returns -------- -Ice.Endpoint - The endpoint from which the connection was created.)"; - - constexpr const char* connectionSetBufferSize_doc = R"(setBufferSize(rcvSize: int, sndSize: int, /) -> None - -Sets the size of the receive and send buffers. - -Parameters ----------- -rcvSize : int - The size of the receive buffer. -sndSize : int - The size of the send buffer.)"; - - constexpr const char* connectionThrowException_doc = R"(throwException() -> None - -Raises an exception that provides the reason for the closure of this connection. For example, this method -raises :class:`Ice.CloseConnectionException` when the connection was closed gracefully by the peer; it raises -:class:`Ice.ConnectionAbortedException` when the connection is aborted with :meth:`~Ice.Connection.abort`. -This method does nothing if the connection is not yet closing or closed.)"; } namespace IcePy @@ -773,51 +594,54 @@ connectionThrowException(ConnectionObject* self, PyObject* /*args*/) } static PyMethodDef ConnectionMethods[] = { - {"abort", reinterpret_cast(connectionAbort), METH_NOARGS, PyDoc_STR(connectionAbort_doc)}, - {"close", reinterpret_cast(connectionClose), METH_NOARGS, PyDoc_STR(connectionClose_doc)}, + {"abort", reinterpret_cast(connectionAbort), METH_NOARGS, PyDoc_STR(IcePy_DOC_Connection_abort)}, + {"close", reinterpret_cast(connectionClose), METH_NOARGS, PyDoc_STR(IcePy_DOC_Connection_close)}, {"createProxy", reinterpret_cast(connectionCreateProxy), METH_VARARGS, - PyDoc_STR(connectionCreateProxy_doc)}, + PyDoc_STR(IcePy_DOC_Connection_createProxy)}, {"disableInactivityCheck", reinterpret_cast(connectionDisableInactivityCheck), METH_NOARGS, - PyDoc_STR(connectionDisableInactivityCheck_doc)}, + PyDoc_STR(IcePy_DOC_Connection_disableInactivityCheck)}, {"setAdapter", reinterpret_cast(connectionSetAdapter), METH_VARARGS, - PyDoc_STR(connectionSetAdapter_doc)}, + PyDoc_STR(IcePy_DOC_Connection_setAdapter)}, {"getAdapter", reinterpret_cast(connectionGetAdapter), METH_NOARGS, - PyDoc_STR(connectionGetAdapter_doc)}, + PyDoc_STR(IcePy_DOC_Connection_getAdapter)}, {"flushBatchRequests", reinterpret_cast(connectionFlushBatchRequests), METH_VARARGS, - PyDoc_STR(connectionFlushBatchRequests_doc)}, + PyDoc_STR(IcePy_DOC_Connection_flushBatchRequests)}, {"flushBatchRequestsAsync", reinterpret_cast(connectionFlushBatchRequestsAsync), METH_VARARGS, - PyDoc_STR(connectionFlushBatchRequestsAsync_doc)}, + PyDoc_STR(IcePy_DOC_Connection_flushBatchRequestsAsync)}, {"setCloseCallback", reinterpret_cast(connectionSetCloseCallback), METH_VARARGS, - PyDoc_STR(connectionSetCloseCallback_doc)}, - {"type", reinterpret_cast(connectionType), METH_NOARGS, PyDoc_STR(connectionType_doc)}, - {"toString", reinterpret_cast(connectionToString), METH_NOARGS, PyDoc_STR(connectionToString_doc)}, - {"getInfo", reinterpret_cast(connectionGetInfo), METH_NOARGS, PyDoc_STR(connectionGetInfo_doc)}, + PyDoc_STR(IcePy_DOC_Connection_setCloseCallback)}, + {"type", reinterpret_cast(connectionType), METH_NOARGS, PyDoc_STR(IcePy_DOC_Connection_type)}, + {"toString", + reinterpret_cast(connectionToString), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_Connection_toString)}, + {"getInfo", reinterpret_cast(connectionGetInfo), METH_NOARGS, PyDoc_STR(IcePy_DOC_Connection_getInfo)}, {"getEndpoint", reinterpret_cast(connectionGetEndpoint), METH_NOARGS, - PyDoc_STR(connectionGetEndpoint_doc)}, + PyDoc_STR(IcePy_DOC_Connection_getEndpoint)}, {"setBufferSize", reinterpret_cast(connectionSetBufferSize), METH_VARARGS, - PyDoc_STR(connectionSetBufferSize_doc)}, + PyDoc_STR(IcePy_DOC_Connection_setBufferSize)}, {"throwException", reinterpret_cast(connectionThrowException), METH_NOARGS, - PyDoc_STR(connectionThrowException_doc)}, + PyDoc_STR(IcePy_DOC_Connection_throwException)}, {} /* sentinel */ }; @@ -831,7 +655,7 @@ namespace IcePy .tp_dealloc = reinterpret_cast(connectionDealloc), .tp_hash = reinterpret_cast(connectionHash), .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = PyDoc_STR("Represents a connection that uses the Ice protocol."), + .tp_doc = PyDoc_STR(IcePy_DOC_Connection), .tp_richcompare = reinterpret_cast(connectionCompare), .tp_methods = ConnectionMethods, .tp_new = reinterpret_cast(connectionNew), diff --git a/python/modules/IcePy/ConnectionInfo.cpp b/python/modules/IcePy/ConnectionInfo.cpp index dc22cde13dd..d750ed47376 100644 --- a/python/modules/IcePy/ConnectionInfo.cpp +++ b/python/modules/IcePy/ConnectionInfo.cpp @@ -2,6 +2,7 @@ #include "ConnectionInfo.h" #include "../../cpp/src/Ice/SSL/SSLUtil.h" +#include "DocStrings.h" #include "EndpointInfo.h" #include "Ice/Ice.h" #include "Util.h" @@ -175,23 +176,22 @@ static PyGetSetDef ConnectionInfoGetters[] = { {"underlying", reinterpret_cast(connectionInfoGetUnderlying), nullptr, - PyDoc_STR("ConnectionInfo | None: The information of the underlying transport or ``None`` if there's no " - "underlying transport."), + PyDoc_STR(IcePy_DOC_ConnectionInfo_underlying), nullptr}, {"incoming", reinterpret_cast(connectionInfoGetIncoming), nullptr, - PyDoc_STR("bool: ``True`` if this is an incoming connection, ``False`` otherwise."), + PyDoc_STR(IcePy_DOC_ConnectionInfo_incoming), nullptr}, {"adapterName", reinterpret_cast(connectionInfoGetAdapterName), nullptr, - PyDoc_STR("str: The name of the adapter associated with the connection."), + PyDoc_STR(IcePy_DOC_ConnectionInfo_adapterName), nullptr}, {"connectionId", reinterpret_cast(connectionInfoGetConnectionId), nullptr, - PyDoc_STR("str: The connection ID."), + PyDoc_STR(IcePy_DOC_ConnectionInfo_connectionId), nullptr}, {} /* sentinel */ }; @@ -200,22 +200,22 @@ static PyGetSetDef IPConnectionInfoGetters[] = { {"localAddress", reinterpret_cast(ipConnectionInfoGetLocalAddress), nullptr, - PyDoc_STR("str: The local address."), + PyDoc_STR(IcePy_DOC_IPConnectionInfo_localAddress), nullptr}, {"localPort", reinterpret_cast(ipConnectionInfoGetLocalPort), nullptr, - PyDoc_STR("int: The local port."), + PyDoc_STR(IcePy_DOC_IPConnectionInfo_localPort), nullptr}, {"remoteAddress", reinterpret_cast(ipConnectionInfoGetRemoteAddress), nullptr, - PyDoc_STR("str: The remote address."), + PyDoc_STR(IcePy_DOC_IPConnectionInfo_remoteAddress), nullptr}, {"remotePort", reinterpret_cast(ipConnectionInfoGetRemotePort), nullptr, - PyDoc_STR("int: The remote port."), + PyDoc_STR(IcePy_DOC_IPConnectionInfo_remotePort), nullptr}, {} /* sentinel */ }; @@ -224,12 +224,12 @@ static PyGetSetDef TCPConnectionInfoGetters[] = { {"rcvSize", reinterpret_cast(tcpConnectionInfoGetRcvSize), nullptr, - PyDoc_STR("int: The size of the receive buffer."), + PyDoc_STR(IcePy_DOC_TCPConnectionInfo_rcvSize), nullptr}, {"sndSize", reinterpret_cast(tcpConnectionInfoGetSndSize), nullptr, - PyDoc_STR("int: The size of the send buffer."), + PyDoc_STR(IcePy_DOC_TCPConnectionInfo_sndSize), nullptr}, {} /* sentinel */ }; @@ -238,22 +238,22 @@ static PyGetSetDef UDPConnectionInfoGetters[] = { {"mcastAddress", reinterpret_cast(udpConnectionInfoGetMcastAddress), nullptr, - PyDoc_STR("str: The multicast address."), + PyDoc_STR(IcePy_DOC_UDPConnectionInfo_mcastAddress), nullptr}, {"mcastPort", reinterpret_cast(udpConnectionInfoGetMcastPort), nullptr, - PyDoc_STR("int: The multicast port."), + PyDoc_STR(IcePy_DOC_UDPConnectionInfo_mcastPort), nullptr}, {"rcvSize", reinterpret_cast(udpConnectionInfoGetRcvSize), nullptr, - PyDoc_STR("int: The size of the receive buffer."), + PyDoc_STR(IcePy_DOC_UDPConnectionInfo_rcvSize), nullptr}, {"sndSize", reinterpret_cast(udpConnectionInfoGetSndSize), nullptr, - PyDoc_STR("int: The size of the send buffer."), + PyDoc_STR(IcePy_DOC_UDPConnectionInfo_sndSize), nullptr}, {} /* sentinel */ }; @@ -262,8 +262,7 @@ static PyGetSetDef WSConnectionInfoGetters[] = { {"headers", reinterpret_cast(wsConnectionInfoGetHeaders), nullptr, - PyDoc_STR("dict[str, str]: The HTTP headers from the WebSocket upgrade handshake, with the request headers for " - "an incoming connection and the response headers for an outgoing connection."), + PyDoc_STR(IcePy_DOC_WSConnectionInfo_headers), nullptr}, {} /* sentinel */ }; @@ -272,7 +271,7 @@ static PyGetSetDef SSLConnectionInfoGetters[] = { {"peerCertificate", reinterpret_cast(sslConnectionInfoGetPeerCertificate), nullptr, - PyDoc_STR("str: The peer certificate, PEM-encoded, or an empty string if the peer did not provide one."), + PyDoc_STR(IcePy_DOC_SSLConnectionInfo_peerCertificate), nullptr}, {} /* sentinel */ }; @@ -286,7 +285,7 @@ namespace IcePy .tp_basicsize = sizeof(ConnectionInfoObject), .tp_dealloc = reinterpret_cast(connectionInfoDealloc), .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, - .tp_doc = PyDoc_STR("Base class for all connection info classes."), + .tp_doc = PyDoc_STR(IcePy_DOC_ConnectionInfo), .tp_getset = ConnectionInfoGetters, .tp_new = reinterpret_cast(connectionInfoNew), }; @@ -297,7 +296,7 @@ namespace IcePy .tp_basicsize = sizeof(ConnectionInfoObject), .tp_dealloc = reinterpret_cast(connectionInfoDealloc), .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, - .tp_doc = PyDoc_STR("Provides access to the connection details of an IP connection."), + .tp_doc = PyDoc_STR(IcePy_DOC_IPConnectionInfo), .tp_getset = IPConnectionInfoGetters, .tp_new = reinterpret_cast(connectionInfoNew), }; @@ -308,7 +307,7 @@ namespace IcePy .tp_basicsize = sizeof(ConnectionInfoObject), .tp_dealloc = reinterpret_cast(connectionInfoDealloc), .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, - .tp_doc = PyDoc_STR("Provides access to the connection details of a TCP connection."), + .tp_doc = PyDoc_STR(IcePy_DOC_TCPConnectionInfo), .tp_getset = TCPConnectionInfoGetters, .tp_new = reinterpret_cast(connectionInfoNew), }; @@ -319,7 +318,7 @@ namespace IcePy .tp_basicsize = sizeof(ConnectionInfoObject), .tp_dealloc = reinterpret_cast(connectionInfoDealloc), .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, - .tp_doc = PyDoc_STR("Provides access to the connection details of a UDP connection."), + .tp_doc = PyDoc_STR(IcePy_DOC_UDPConnectionInfo), .tp_getset = UDPConnectionInfoGetters, .tp_new = reinterpret_cast(connectionInfoNew), }; @@ -330,7 +329,7 @@ namespace IcePy .tp_basicsize = sizeof(ConnectionInfoObject), .tp_dealloc = reinterpret_cast(connectionInfoDealloc), .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, - .tp_doc = PyDoc_STR("Provides access to the connection details of a WebSocket connection."), + .tp_doc = PyDoc_STR(IcePy_DOC_WSConnectionInfo), .tp_getset = WSConnectionInfoGetters, .tp_new = reinterpret_cast(connectionInfoNew), }; @@ -341,7 +340,7 @@ namespace IcePy .tp_basicsize = sizeof(ConnectionInfoObject), .tp_dealloc = reinterpret_cast(connectionInfoDealloc), .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, - .tp_doc = PyDoc_STR("Provides access to the connection details of an SSL connection."), + .tp_doc = PyDoc_STR(IcePy_DOC_SSLConnectionInfo), .tp_getset = SSLConnectionInfoGetters, .tp_new = reinterpret_cast(connectionInfoNew), }; diff --git a/python/modules/IcePy/DocStrings.h b/python/modules/IcePy/DocStrings.h new file mode 100644 index 00000000000..e931e9aef53 --- /dev/null +++ b/python/modules/IcePy/DocStrings.h @@ -0,0 +1,872 @@ +// Copyright (c) ZeroC, Inc. + +// Generated by scripts/generateIcePyDocs.py from python/python/IcePy-stubs/__init__.pyi. Do not edit. + +#ifndef ICEPY_DOC_STRINGS_H +#define ICEPY_DOC_STRINGS_H + +// clang-format off + +inline constexpr const char* IcePy_DOC_module = "The Internet Communications Engine."; + +inline constexpr const char* IcePy_DOC_AsyncInvocationContext = "IcePy.AsyncInvocationContext"; + +inline constexpr const char* IcePy_DOC_AsyncInvocationContext_cancel = "cancel() -> None"; + +inline constexpr const char* IcePy_DOC_BatchRequest = R"doc(Represents a batch request. +A batch request is created by invoking an operation on a batch-oneway or batch-datagram proxy.)doc"; + +inline constexpr const char* IcePy_DOC_BatchRequest_enqueue = R"doc(enqueue() -> None + +Queues this request.)doc"; + +inline constexpr const char* IcePy_DOC_BatchRequest_getOperation = R"doc(getOperation() -> str + +Gets the name of the operation. + +Returns +------- +str + The operation name.)doc"; + +inline constexpr const char* IcePy_DOC_BatchRequest_getProxy = R"doc(getProxy() -> Ice.ObjectPrx + +Gets the proxy used to create this batch request. + +Returns +------- +Ice.ObjectPrx + The proxy.)doc"; + +inline constexpr const char* IcePy_DOC_BatchRequest_getSize = R"doc(getSize() -> int + +Gets the size of the request. + +Returns +------- +int + The number of bytes consumed by the request.)doc"; + +inline constexpr const char* IcePy_DOC_Communicator = "Communicator(initData: Ice.InitializationData | None, /) -> None"; + +inline constexpr const char* IcePy_DOC_Communicator__getWrapper = "_getWrapper() -> Ice.Communicator"; + +inline constexpr const char* IcePy_DOC_Communicator__setWrapper = "_setWrapper(wrapper: Ice.Communicator, /) -> None"; + +inline constexpr const char* IcePy_DOC_Communicator_addAdminFacet = "addAdminFacet(servant: Ice.Object, facet: str, /) -> None"; + +inline constexpr const char* IcePy_DOC_Communicator_createAdmin = "createAdmin(adminAdapter: Ice.ObjectAdapter | None, adminIdentity: Ice.Identity, /) -> Ice.ObjectPrx"; + +inline constexpr const char* IcePy_DOC_Communicator_createObjectAdapter = "createObjectAdapter(name: str, /) -> ObjectAdapter"; + +inline constexpr const char* IcePy_DOC_Communicator_createObjectAdapterWithEndpoints = "createObjectAdapterWithEndpoints(name: str, endpoints: str, /) -> ObjectAdapter"; + +inline constexpr const char* IcePy_DOC_Communicator_createObjectAdapterWithRouter = "createObjectAdapterWithRouter(name: str, router: Ice.RouterPrx, /) -> ObjectAdapter"; + +inline constexpr const char* IcePy_DOC_Communicator_destroy = "destroy() -> None"; + +inline constexpr const char* IcePy_DOC_Communicator_destroyAsync = "destroyAsync(callable: Callable, /) -> None"; + +inline constexpr const char* IcePy_DOC_Communicator_findAdminFacet = "findAdminFacet(facet: str, /) -> Ice.Object | NativePropertiesAdmin | None"; + +inline constexpr const char* IcePy_DOC_Communicator_findAllAdminFacets = "findAllAdminFacets() -> dict[str, Ice.Object | NativePropertiesAdmin]"; + +inline constexpr const char* IcePy_DOC_Communicator_flushBatchRequests = "flushBatchRequests(compress: Ice.CompressBatch, /) -> None"; + +inline constexpr const char* IcePy_DOC_Communicator_flushBatchRequestsAsync = "flushBatchRequestsAsync(compress: Ice.CompressBatch, /) -> Awaitable[None]"; + +inline constexpr const char* IcePy_DOC_Communicator_getAdmin = "getAdmin() -> Ice.ObjectPrx | None"; + +inline constexpr const char* IcePy_DOC_Communicator_getDefaultLocator = "getDefaultLocator() -> Ice.LocatorPrx | None"; + +inline constexpr const char* IcePy_DOC_Communicator_getDefaultObjectAdapter = "getDefaultObjectAdapter() -> Ice.ObjectAdapter | None"; + +inline constexpr const char* IcePy_DOC_Communicator_getDefaultRouter = "getDefaultRouter() -> Ice.RouterPrx | None"; + +inline constexpr const char* IcePy_DOC_Communicator_getImplicitContext = "getImplicitContext() -> ImplicitContext | None"; + +inline constexpr const char* IcePy_DOC_Communicator_getLogger = "getLogger() -> Ice.Logger | Logger"; + +inline constexpr const char* IcePy_DOC_Communicator_getProperties = "getProperties() -> Properties"; + +inline constexpr const char* IcePy_DOC_Communicator_identityToString = "identityToString(identity: Ice.Identity, /) -> str"; + +inline constexpr const char* IcePy_DOC_Communicator_isShutdown = "isShutdown() -> bool"; + +inline constexpr const char* IcePy_DOC_Communicator_propertyToProxy = "propertyToProxy(property: str, /) -> Ice.ObjectPrx | None"; + +inline constexpr const char* IcePy_DOC_Communicator_proxyToProperty = "proxyToProperty(proxy: Ice.ObjectPrx, property: str, /) -> dict[str, str]"; + +inline constexpr const char* IcePy_DOC_Communicator_proxyToString = "proxyToString(proxy: Ice.ObjectPrx | None, /) -> str"; + +inline constexpr const char* IcePy_DOC_Communicator_removeAdminFacet = "removeAdminFacet(facet: str, /) -> Ice.Object | None"; + +inline constexpr const char* IcePy_DOC_Communicator_setDefaultLocator = "setDefaultLocator(locator: Ice.LocatorPrx | None, /) -> None"; + +inline constexpr const char* IcePy_DOC_Communicator_setDefaultObjectAdapter = "setDefaultObjectAdapter(adapter: Ice.ObjectAdapter | None, /) -> None"; + +inline constexpr const char* IcePy_DOC_Communicator_setDefaultRouter = "setDefaultRouter(router: Ice.RouterPrx | None, /) -> None"; + +inline constexpr const char* IcePy_DOC_Communicator_shutdown = "shutdown() -> None"; + +inline constexpr const char* IcePy_DOC_Communicator_shutdownCompleted = "shutdownCompleted() -> Awaitable[None]"; + +inline constexpr const char* IcePy_DOC_Communicator_stringToProxy = "stringToProxy(str: str, /) -> Ice.ObjectPrx | None"; + +inline constexpr const char* IcePy_DOC_Communicator_waitForShutdown = "waitForShutdown(timeout: int, /) -> bool"; + +inline constexpr const char* IcePy_DOC_Connection = "Represents a connection that uses the Ice protocol."; + +inline constexpr const char* IcePy_DOC_Connection_abort = R"doc(abort() -> None + +Aborts this connection.)doc"; + +inline constexpr const char* IcePy_DOC_Connection_close = R"doc(close() -> Awaitable[None] + +Starts a graceful closure of this connection once all outstanding invocations have completed. + +Returns +------- +Awaitable[None] + A future that becomes available when the connection is closed. If the connection was lost or + aborted, awaiting this future raises the exception that caused the connection's closure.)doc"; + +inline constexpr const char* IcePy_DOC_Connection_createProxy = R"doc(createProxy(identity: Ice.Identity, /) -> Ice.ObjectPrx + +Creates a special proxy (a 'fixed proxy') that always uses this connection. + +Parameters +---------- +identity : Ice.Identity + The identity of the target object. + +Returns +------- +Ice.ObjectPrx + A fixed proxy with the provided identity. + +Raises +------ +CommunicatorDestroyedException + If the communicator has been destroyed.)doc"; + +inline constexpr const char* IcePy_DOC_Connection_disableInactivityCheck = R"doc(disableInactivityCheck() -> None + +Disables the inactivity check on this connection. + +By default, Ice will close connections that remain inactive for a certain period. +This method disables that behavior for this connection.)doc"; + +inline constexpr const char* IcePy_DOC_Connection_setAdapter = R"doc(setAdapter(adapter: Ice.ObjectAdapter | None, /) -> None + +Associates an object adapter with this connection. + +When a connection receives a request, it dispatches this request using its associated object adapter. +If the associated object adapter is ``None``, the connection rejects any incoming request with an +:class:`Ice.ObjectNotExistException`. + +The default object adapter of an incoming connection is the object adapter that created this connection; +the default object adapter of an outgoing connection is the communicator's default object adapter. + +Parameters +---------- +adapter : Ice.ObjectAdapter | None + The object adapter to associate with this connection. + +Raises +------ +LocalException + If this connection is an incoming (server) connection: only outgoing (client) connections + support setting the object adapter.)doc"; + +inline constexpr const char* IcePy_DOC_Connection_getAdapter = R"doc(getAdapter() -> Ice.ObjectAdapter | None + +Gets the object adapter associated with this connection. + +Returns +------- +Ice.ObjectAdapter | None + The object adapter associated with this connection.)doc"; + +inline constexpr const char* IcePy_DOC_Connection_flushBatchRequests = R"doc(flushBatchRequests(compress: Ice.CompressBatch, /) -> None + +Flushes any pending batch requests for this connection. + +This corresponds to all batch requests invoked on fixed proxies associated with the connection. + +Parameters +---------- +compress : Ice.CompressBatch + Specifies whether or not the queued batch requests should be compressed before being sent over the wire. + +Raises +------ +LocalException + If the flush fails. For example, this method raises CommunicatorDestroyedException if the communicator + has been destroyed.)doc"; + +inline constexpr const char* IcePy_DOC_Connection_flushBatchRequestsAsync = R"doc(flushBatchRequestsAsync(compress: Ice.CompressBatch, /) -> Awaitable[None] + +Flushes any pending batch requests for this connection asynchronously. + +This corresponds to all batch requests invoked on fixed proxies associated with the connection. + +Parameters +---------- +compress : Ice.CompressBatch + Specifies whether or not the queued batch requests should be compressed before being sent over the wire. + +Returns +------- +Awaitable[None] + A future that becomes available when the flush completes. + +Raises +------ +CommunicatorDestroyedException + If the communicator has been destroyed. This exception is raised synchronously.)doc"; + +inline constexpr const char* IcePy_DOC_Connection_setCloseCallback = R"doc(setCloseCallback(callback: Callable[[Connection], None] | None, /) -> None + +Sets a close callback on the connection. The callback is called by the connection when it's closed. +The callback is called from the Ice thread pool associated with the connection. + +Parameters +---------- +callback : Callable[[Connection], None] | None + The close callback callable, or ``None`` to remove the current callback.)doc"; + +inline constexpr const char* IcePy_DOC_Connection_type = R"doc(type() -> str + +Returns the connection type. This corresponds to the endpoint type, such as 'tcp', 'udp', etc. + +Returns +------- +str + The type of the connection.)doc"; + +inline constexpr const char* IcePy_DOC_Connection_toString = R"doc(toString() -> str + +Returns a description of the connection as human readable text, suitable for logging or error messages. + +Notes +----- +This method remains usable after the connection is closed or aborted. + +Returns +------- +str + The description of the connection as human readable text.)doc"; + +inline constexpr const char* IcePy_DOC_Connection_getInfo = R"doc(getInfo() -> Ice.ConnectionInfo + +Returns the connection information. + +Returns +------- +Ice.ConnectionInfo + The connection information.)doc"; + +inline constexpr const char* IcePy_DOC_Connection_getEndpoint = R"doc(getEndpoint() -> Ice.Endpoint + +Gets the endpoint from which the connection was created. + +Returns +------- +Ice.Endpoint + The endpoint from which the connection was created.)doc"; + +inline constexpr const char* IcePy_DOC_Connection_setBufferSize = R"doc(setBufferSize(rcvSize: int, sndSize: int, /) -> None + +Sets the size of the receive and send buffers. + +Parameters +---------- +rcvSize : int + The size of the receive buffer. +sndSize : int + The size of the send buffer.)doc"; + +inline constexpr const char* IcePy_DOC_Connection_throwException = R"doc(throwException() -> None + +Raises an exception that provides the reason for the closure of this connection. For example, this method +raises :class:`Ice.CloseConnectionException` when the connection was closed gracefully by the peer; it raises +:class:`Ice.ConnectionAbortedException` when the connection is aborted with :meth:`~Ice.Connection.abort`. +This method does nothing if the connection is not yet closing or closed.)doc"; + +inline constexpr const char* IcePy_DOC_ConnectionInfo = "Base class for all connection info classes."; + +inline constexpr const char* IcePy_DOC_ConnectionInfo_underlying = "ConnectionInfo | None: The information of the underlying transport or ``None`` if there's no underlying transport."; + +inline constexpr const char* IcePy_DOC_ConnectionInfo_incoming = "bool: ``True`` if this is an incoming connection, ``False`` otherwise."; + +inline constexpr const char* IcePy_DOC_ConnectionInfo_adapterName = "str: The name of the adapter associated with the connection."; + +inline constexpr const char* IcePy_DOC_ConnectionInfo_connectionId = "str: The connection ID."; + +inline constexpr const char* IcePy_DOC_DispatchCallback = "IcePy.DispatchCallback"; + +inline constexpr const char* IcePy_DOC_DispatchCallback_response = "response(result: Any, /) -> None"; + +inline constexpr const char* IcePy_DOC_DispatchCallback_exception = "exception(exception: BaseException, /) -> None"; + +inline constexpr const char* IcePy_DOC_Endpoint = R"doc(An endpoint specifies the address of the server-end of an Ice connection. +An object adapter listens on one or more endpoints and a client establishes a connection to an endpoint.)doc"; + +inline constexpr const char* IcePy_DOC_Endpoint_toString = R"doc(toString() -> str + +Returns a string representation of this endpoint. + +Returns +------- +str + The string representation of this endpoint.)doc"; + +inline constexpr const char* IcePy_DOC_Endpoint_getInfo = R"doc(getInfo() -> EndpointInfo + +Returns this endpoint's information. + +Returns +------- +EndpointInfo + This endpoint's information class.)doc"; + +inline constexpr const char* IcePy_DOC_EndpointInfo = "Base class for the endpoint info classes."; + +inline constexpr const char* IcePy_DOC_EndpointInfo_underlying = "Ice.EndpointInfo | None: The information of the underlying endpoint or ``None`` if there's no underlying endpoint."; + +inline constexpr const char* IcePy_DOC_EndpointInfo_compress = "bool: Specifies whether or not compression should be used if available when using this endpoint."; + +inline constexpr const char* IcePy_DOC_EndpointInfo_type = R"doc(type() -> int + +Returns the type of the endpoint. + +Returns +------- +int + The endpoint type.)doc"; + +inline constexpr const char* IcePy_DOC_EndpointInfo_datagram = R"doc(datagram() -> bool + +Returns whether this endpoint is a datagram endpoint (namely, UDP). + +Returns +------- +bool + ``True`` for a UDP endpoint, ``False`` otherwise.)doc"; + +inline constexpr const char* IcePy_DOC_EndpointInfo_secure = R"doc(secure() -> bool + +Returns whether this endpoint uses SSL. + +Returns +------- +bool + ``True`` for SSL and SSL-based transports, ``False`` otherwise.)doc"; + +inline constexpr const char* IcePy_DOC_ExceptionInfo = "IcePy.ExceptionInfo"; + +inline constexpr const char* IcePy_DOC_ExecutorCall = "IcePy.ExecutorCall"; + +inline constexpr const char* IcePy_DOC_IPConnectionInfo = "Provides access to the connection details of an IP connection."; + +inline constexpr const char* IcePy_DOC_IPConnectionInfo_localAddress = "str: The local address."; + +inline constexpr const char* IcePy_DOC_IPConnectionInfo_localPort = "int: The local port."; + +inline constexpr const char* IcePy_DOC_IPConnectionInfo_remoteAddress = "str: The remote address."; + +inline constexpr const char* IcePy_DOC_IPConnectionInfo_remotePort = "int: The remote port."; + +inline constexpr const char* IcePy_DOC_IPEndpointInfo = "Provides access to the address details of an IP endpoint."; + +inline constexpr const char* IcePy_DOC_IPEndpointInfo_host = "str: The host or address configured with the endpoint."; + +inline constexpr const char* IcePy_DOC_IPEndpointInfo_port = "int: The port number."; + +inline constexpr const char* IcePy_DOC_IPEndpointInfo_sourceAddress = "str: The source IP address."; + +inline constexpr const char* IcePy_DOC_ImplicitContext = "IcePy.ImplicitContext"; + +inline constexpr const char* IcePy_DOC_ImplicitContext_containsKey = "containsKey(key: str, /) -> bool"; + +inline constexpr const char* IcePy_DOC_ImplicitContext_get = "get(key: str, /) -> str"; + +inline constexpr const char* IcePy_DOC_ImplicitContext_getContext = "getContext() -> dict[str, str]"; + +inline constexpr const char* IcePy_DOC_ImplicitContext_put = "put(key: str, value: str, /) -> str"; + +inline constexpr const char* IcePy_DOC_ImplicitContext_remove = "remove(key: str, /) -> str"; + +inline constexpr const char* IcePy_DOC_ImplicitContext_setContext = "setContext(newContext: dict[str, str], /) -> None"; + +inline constexpr const char* IcePy_DOC_Logger = "IcePy.Logger"; + +inline constexpr const char* IcePy_DOC_Logger_cloneWithPrefix = "cloneWithPrefix(prefix: str, /) -> Logger"; + +inline constexpr const char* IcePy_DOC_Logger_error = "error(message: str, /) -> None"; + +inline constexpr const char* IcePy_DOC_Logger_getPrefix = "getPrefix() -> str"; + +inline constexpr const char* IcePy_DOC_Logger_print = "print(message: str, /) -> None"; + +inline constexpr const char* IcePy_DOC_Logger_trace = "trace(category: str, message: str, /) -> None"; + +inline constexpr const char* IcePy_DOC_Logger_warning = "warning(message: str, /) -> None"; + +inline constexpr const char* IcePy_DOC_NativePropertiesAdmin = "The default implementation of the 'Properties' admin facet."; + +inline constexpr const char* IcePy_DOC_NativePropertiesAdmin_addUpdateCallback = R"doc(addUpdateCallback(callback: Callable[[dict[str, str]], None], /) -> None + +Registers an update callback that will be invoked when a property update occurs. + +Parameters +---------- +callback : Callable[[dict[str, str]], None] + The callback.)doc"; + +inline constexpr const char* IcePy_DOC_NativePropertiesAdmin_removeUpdateCallback = R"doc(removeUpdateCallback(callback: Callable[[dict[str, str]], None], /) -> None + +Removes a previously registered update callback. + +Parameters +---------- +callback : Callable[[dict[str, str]], None] + The callback to remove.)doc"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter = "IcePy.ObjectAdapter"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_activate = "activate() -> None"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_add = "add(servant: Ice.Object, id: Ice.Identity, /) -> Ice.ObjectPrx"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_addDefaultServant = "addDefaultServant(servant: Ice.Object, category: str, /) -> None"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_addFacet = "addFacet(servant: Ice.Object, id: Ice.Identity, facet: str, /) -> Ice.ObjectPrx"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_addFacetWithUUID = "addFacetWithUUID(servant: Ice.Object, facet: str, /) -> Ice.ObjectPrx"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_addServantLocator = "addServantLocator(locator: Ice.ServantLocator, category: str, /) -> None"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_addWithUUID = "addWithUUID(servant: Ice.Object, /) -> Ice.ObjectPrx"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_createDirectProxy = "createDirectProxy(identity: Ice.Identity, /) -> Ice.ObjectPrx"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_createIndirectProxy = "createIndirectProxy(identity: Ice.Identity, /) -> Ice.ObjectPrx"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_createProxy = "createProxy(identity: Ice.Identity, /) -> Ice.ObjectPrx"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_deactivate = "deactivate() -> None"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_destroy = "destroy() -> None"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_find = "find(identity: Ice.Identity, /) -> Ice.Object | None"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_findAllFacets = "findAllFacets(id: Ice.Identity, /) -> dict[str, Ice.Object]"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_findByProxy = "findByProxy(proxy: Ice.ObjectPrx, /) -> Ice.Object | None"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_findDefaultServant = "findDefaultServant(category: str, /) -> Ice.Object | None"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_findFacet = "findFacet(id: Ice.Identity, facet: str, /) -> Ice.Object | None"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_findServantLocator = "findServantLocator(category: str, /) -> Ice.ServantLocator | None"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_getCommunicator = "getCommunicator() -> Communicator"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_getEndpoints = "getEndpoints() -> tuple[Endpoint, ...]"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_getLocator = "getLocator() -> Ice.LocatorPrx | None"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_getName = "getName() -> str"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_getPublishedEndpoints = "getPublishedEndpoints() -> tuple[Endpoint, ...]"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_hold = "hold() -> None"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_isDeactivated = "isDeactivated() -> bool"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_remove = "remove(id: Ice.Identity, /) -> Ice.Object"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_removeAllFacets = "removeAllFacets(id: Ice.Identity, /) -> dict[str, Ice.Object]"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_removeDefaultServant = "removeDefaultServant(category: str, /) -> Ice.Object"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_removeFacet = "removeFacet(id: Ice.Identity, facet: str, /) -> Ice.Object"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_removeServantLocator = "removeServantLocator(category: str, /) -> Ice.ServantLocator"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_setLocator = "setLocator(locator: Ice.LocatorPrx | None, /) -> None"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_setPublishedEndpoints = "setPublishedEndpoints(newEndpoints: tuple[Endpoint, ...] | list[Endpoint], /) -> None"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_waitForDeactivate = "waitForDeactivate(timeout: int, /) -> bool"; + +inline constexpr const char* IcePy_DOC_ObjectAdapter_waitForHold = "waitForHold(timeout: int, /) -> bool"; + +inline constexpr const char* IcePy_DOC_ObjectPrx = "ObjectPrx(communicator: Ice.Communicator, proxyString: str, /) -> None"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_adapterId = "ice_adapterId(newAdapterId: str, /) -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_batchDatagram = "ice_batchDatagram() -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_batchOneway = "ice_batchOneway() -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_collocationOptimized = "ice_collocationOptimized(collocated: bool, /) -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_compress = "ice_compress(compress: bool, /) -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_connectionCached = "ice_connectionCached(newCache: bool, /) -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_connectionId = "ice_connectionId(connectionId: str, /) -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_context = "ice_context(new_context: dict[str, str], /) -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_datagram = "ice_datagram() -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_encodingVersion = "ice_encodingVersion(version: Ice.EncodingVersion, /) -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_endpointSelection = "ice_endpointSelection(newType: Ice.EndpointSelectionType, /) -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_endpoints = "ice_endpoints(newEndpoints: tuple[Endpoint, ...] | list[Endpoint], /) -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_facet = "ice_facet(new_facet: str, /) -> Ice.ObjectPrx"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_fixed = "ice_fixed(connection: Ice.Connection, /) -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_flushBatchRequests = "ice_flushBatchRequests() -> None"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_flushBatchRequestsAsync = "ice_flushBatchRequestsAsync() -> Awaitable[None]"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_getAdapterId = "ice_getAdapterId() -> str"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_getCachedConnection = "ice_getCachedConnection() -> Ice.Connection | None"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_getCommunicator = "ice_getCommunicator() -> Ice.Communicator"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_getCompress = "ice_getCompress() -> bool | None"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_getConnection = "ice_getConnection() -> Ice.Connection | None"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_getConnectionAsync = "ice_getConnectionAsync() -> Awaitable[Ice.Connection | None]"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_getConnectionId = "ice_getConnectionId() -> str"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_getContext = "ice_getContext() -> dict[str, str]"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_getEncodingVersion = "ice_getEncodingVersion() -> Ice.EncodingVersion"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_getEndpointSelection = "ice_getEndpointSelection() -> Ice.EndpointSelectionType"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_getEndpoints = "ice_getEndpoints() -> tuple[Endpoint, ...]"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_getFacet = "ice_getFacet() -> str"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_getIdentity = "ice_getIdentity() -> Ice.Identity"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_getInvocationTimeout = "ice_getInvocationTimeout() -> int"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_getLocator = "ice_getLocator() -> Ice.LocatorPrx | None"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_getLocatorCacheTimeout = "ice_getLocatorCacheTimeout() -> int"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_getRouter = "ice_getRouter() -> Ice.RouterPrx | None"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_identity = "ice_identity(newIdentity: Ice.Identity, /) -> Ice.ObjectPrx"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_invocationTimeout = "ice_invocationTimeout(timeout: int, /) -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_invoke = "ice_invoke(operation: str, mode: Ice.OperationMode, inParams: bytes, ctx: dict[str, str] | None = None) -> tuple[bool, bytes]"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_invokeAsync = "ice_invokeAsync(operation: str, mode: Ice.OperationMode, inParams: bytes, ctx: dict[str, str] | None = None) -> Awaitable[tuple[bool, bytes]]"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_isBatchDatagram = "ice_isBatchDatagram() -> bool"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_isBatchOneway = "ice_isBatchOneway() -> bool"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_isCollocationOptimized = "ice_isCollocationOptimized() -> bool"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_isConnectionCached = "ice_isConnectionCached() -> bool"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_isDatagram = "ice_isDatagram() -> bool"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_isFixed = "ice_isFixed() -> bool"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_isOneway = "ice_isOneway() -> bool"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_isTwoway = "ice_isTwoway() -> bool"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_locator = "ice_locator(locator: Ice.LocatorPrx | None, /) -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_locatorCacheTimeout = "ice_locatorCacheTimeout(timeout: int, /) -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_oneway = "ice_oneway() -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_router = "ice_router(router: Ice.RouterPrx | None, /) -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_toString = "ice_toString() -> str"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_ice_twoway = "ice_twoway() -> Self"; + +inline constexpr const char* IcePy_DOC_ObjectPrx_newProxy = "newProxy(type: Type[T], proxy: Ice.ObjectPrx, /) -> T"; + +inline constexpr const char* IcePy_DOC_OpaqueEndpointInfo = "Provides access to the details of an opaque endpoint."; + +inline constexpr const char* IcePy_DOC_OpaqueEndpointInfo_rawBytes = "bytes: The raw encoding of the opaque endpoint."; + +inline constexpr const char* IcePy_DOC_OpaqueEndpointInfo_rawEncoding = "Ice.EncodingVersion: The encoding version of the opaque endpoint (to decode or encode the ``rawBytes``)."; + +inline constexpr const char* IcePy_DOC_Operation = "Operation(sliceName: str, mappedName: str, mode: Ice.OperationMode, format: Ice.FormatType | None, metadata: tuple, inParams: tuple, outParams: tuple, returnType: object, exceptions: tuple, onewayOnly: bool, /) -> None"; + +inline constexpr const char* IcePy_DOC_Operation_invoke = "invoke(proxy: ObjectPrx, args: tuple, /) -> Any"; + +inline constexpr const char* IcePy_DOC_Operation_invokeAsync = "invokeAsync(proxy: ObjectPrx, args: tuple, /) -> Awaitable[Any]"; + +inline constexpr const char* IcePy_DOC_Operation_deprecate = "deprecate(reason: str, /)"; + +inline constexpr const char* IcePy_DOC_Properties = "Properties(args: list[str] | None = None, defaults: Ice.Properties | None = None, /) -> None"; + +inline constexpr const char* IcePy_DOC_Properties_getProperty = "getProperty(key: str, /) -> str"; + +inline constexpr const char* IcePy_DOC_Properties_getIceProperty = "getIceProperty(key: str, /) -> str"; + +inline constexpr const char* IcePy_DOC_Properties_getPropertyWithDefault = "getPropertyWithDefault(key: str, value: str, /) -> str"; + +inline constexpr const char* IcePy_DOC_Properties_getPropertyAsInt = "getPropertyAsInt(key: str, /) -> int"; + +inline constexpr const char* IcePy_DOC_Properties_getIcePropertyAsInt = "getIcePropertyAsInt(key: str, /) -> int"; + +inline constexpr const char* IcePy_DOC_Properties_getPropertyAsIntWithDefault = "getPropertyAsIntWithDefault(key: str, value: int, /) -> int"; + +inline constexpr const char* IcePy_DOC_Properties_getPropertyAsList = "getPropertyAsList(key: str, /) -> list[str]"; + +inline constexpr const char* IcePy_DOC_Properties_getIcePropertyAsList = "getIcePropertyAsList(key: str, /) -> list[str]"; + +inline constexpr const char* IcePy_DOC_Properties_getPropertyAsListWithDefault = "getPropertyAsListWithDefault(key: str, value: list[str], /) -> list[str]"; + +inline constexpr const char* IcePy_DOC_Properties_getPropertiesForPrefix = "getPropertiesForPrefix(prefix: str, /) -> dict[str, str]"; + +inline constexpr const char* IcePy_DOC_Properties_setProperty = "setProperty(key: str, value: str, /) -> None"; + +inline constexpr const char* IcePy_DOC_Properties_getCommandLineOptions = "getCommandLineOptions() -> list[str]"; + +inline constexpr const char* IcePy_DOC_Properties_parseCommandLineOptions = "parseCommandLineOptions(prefix: str, options: list[str], /) -> list[str]"; + +inline constexpr const char* IcePy_DOC_Properties_parseIceCommandLineOptions = "parseIceCommandLineOptions(options: list[str], /) -> list[str]"; + +inline constexpr const char* IcePy_DOC_Properties_load = "load(file: str, /) -> None"; + +inline constexpr const char* IcePy_DOC_Properties_clone = "clone() -> Properties"; + +inline constexpr const char* IcePy_DOC_SSLConnectionInfo = "Provides access to the connection details of an SSL connection."; + +inline constexpr const char* IcePy_DOC_SSLConnectionInfo_peerCertificate = "str: The peer certificate, PEM-encoded, or an empty string if the peer did not provide one."; + +inline constexpr const char* IcePy_DOC_SSLEndpointInfo = "Provides access to an SSL endpoint's information."; + +inline constexpr const char* IcePy_DOC_TCPConnectionInfo = "Provides access to the connection details of a TCP connection."; + +inline constexpr const char* IcePy_DOC_TCPConnectionInfo_rcvSize = "int: The size of the receive buffer."; + +inline constexpr const char* IcePy_DOC_TCPConnectionInfo_sndSize = "int: The size of the send buffer."; + +inline constexpr const char* IcePy_DOC_TCPEndpointInfo = "Provides access to a TCP endpoint's information."; + +inline constexpr const char* IcePy_DOC_UDPConnectionInfo = "Provides access to the connection details of a UDP connection."; + +inline constexpr const char* IcePy_DOC_UDPConnectionInfo_mcastAddress = "str: The multicast address."; + +inline constexpr const char* IcePy_DOC_UDPConnectionInfo_mcastPort = "int: The multicast port."; + +inline constexpr const char* IcePy_DOC_UDPConnectionInfo_rcvSize = "int: The size of the receive buffer."; + +inline constexpr const char* IcePy_DOC_UDPConnectionInfo_sndSize = "int: The size of the send buffer."; + +inline constexpr const char* IcePy_DOC_UDPEndpointInfo = "Provides access to a UDP endpoint's information."; + +inline constexpr const char* IcePy_DOC_UDPEndpointInfo_mcastInterface = "str: The multicast interface."; + +inline constexpr const char* IcePy_DOC_UDPEndpointInfo_mcastTtl = "int: The multicast time-to-live (or hops)."; + +inline constexpr const char* IcePy_DOC_WSConnectionInfo = "Provides access to the connection details of a WebSocket connection."; + +inline constexpr const char* IcePy_DOC_WSConnectionInfo_headers = "dict[str, str]: The HTTP headers from the WebSocket upgrade handshake, with the request headers for an incoming connection and the response headers for an outgoing connection."; + +inline constexpr const char* IcePy_DOC_WSEndpointInfo = "Provides access to a WebSocket endpoint's information."; + +inline constexpr const char* IcePy_DOC_WSEndpointInfo_resource = "str: The URI configured with the endpoint."; + +inline constexpr const char* IcePy_DOC_stringVersion = R"doc(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.)doc"; + +inline constexpr const char* IcePy_DOC_intVersion = R"doc(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.)doc"; + +inline constexpr const char* IcePy_DOC_createProperties = R"doc(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.)doc"; + +inline constexpr const char* IcePy_DOC_stringToIdentity = R"doc(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.)doc"; + +inline constexpr const char* IcePy_DOC_identityToString = R"doc(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.)doc"; + +inline constexpr const char* IcePy_DOC_getProcessLogger = R"doc(getProcessLogger() -> Ice.Logger | Logger + +Gets the per-process logger. + +Returns +------- +Ice.Logger | Logger + The current per-process logger instance.)doc"; + +inline constexpr const char* IcePy_DOC_setProcessLogger = R"doc(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.)doc"; + +inline constexpr const char* IcePy_DOC_loadSlice = R"doc(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.)doc"; + +inline constexpr const char* IcePy_DOC_compileSlice = R"doc(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.)doc"; + +inline constexpr const char* IcePy_DOC_declareProxy = "declareProxy(sliceId: str, /)"; + +inline constexpr const char* IcePy_DOC_defineProxy = "defineProxy(sliceId: str, proxyType: Type[ObjectPrx], /)"; + +inline constexpr const char* IcePy_DOC_declareValue = "declareValue(sliceId: str, /)"; + +inline constexpr const char* IcePy_DOC_defineValue = "defineValue(sliceId: str, valueType: Type[Ice.Value], compactId: int, meta: tuple, isInterface: bool, baseType: Type[Ice.Value] | None, members: tuple, /)"; + +inline constexpr const char* IcePy_DOC_defineDictionary = "defineDictionary(sliceId: str, meta: tuple, keyType: TypeInfo, valueType: TypeInfo, /)"; + +inline constexpr const char* IcePy_DOC_defineEnum = "defineEnum(sliceId: str, type: Type, meta: tuple, enumerators: dict, /)"; + +inline constexpr const char* IcePy_DOC_defineException = "defineException(sliceId: str, type: Type[BaseException], meta: tuple, base: Type[BaseException] | None, members: tuple, /)"; + +inline constexpr const char* IcePy_DOC_defineSequence = "defineSequence(sliceId: str, meta: tuple, elementType: TypeInfo, /)"; + +inline constexpr const char* IcePy_DOC_defineStruct = "defineStruct(sliceId: str, type: Type, meta: tuple, members: tuple, /)"; + +inline constexpr const char* IcePy_DOC_TypeInfo = "IcePy.TypeInfo"; + +// clang-format on + +#endif diff --git a/python/modules/IcePy/Endpoint.cpp b/python/modules/IcePy/Endpoint.cpp index da54fb881e8..3f0283d8670 100644 --- a/python/modules/IcePy/Endpoint.cpp +++ b/python/modules/IcePy/Endpoint.cpp @@ -1,6 +1,7 @@ // Copyright (c) ZeroC, Inc. #include "Endpoint.h" +#include "DocStrings.h" #include "EndpointInfo.h" #include "Ice/TargetCompare.h" #include "Util.h" @@ -8,31 +9,6 @@ using namespace std; using namespace IcePy; -namespace -{ - constexpr const char* endpointToString_doc = R"(toString() -> str - -Returns a string representation of this endpoint. - -Returns -------- -str - The string representation of this endpoint.)"; - - constexpr const char* endpointGetInfo_doc = R"(getInfo() -> EndpointInfo - -Returns this endpoint's information. - -Returns -------- -EndpointInfo - This endpoint's information class.)"; - - constexpr const char* EndpointType_doc = - R"(An endpoint specifies the address of the server-end of an Ice connection. -An object adapter listens on one or more endpoints and a client establishes a connection to an endpoint.)"; -} - namespace IcePy { struct EndpointObject @@ -143,8 +119,8 @@ endpointGetInfo(EndpointObject* self, PyObject* /*args*/) } static PyMethodDef EndpointMethods[] = { - {"toString", reinterpret_cast(endpointToString), METH_NOARGS, PyDoc_STR(endpointToString_doc)}, - {"getInfo", reinterpret_cast(endpointGetInfo), METH_NOARGS, PyDoc_STR(endpointGetInfo_doc)}, + {"toString", reinterpret_cast(endpointToString), METH_NOARGS, PyDoc_STR(IcePy_DOC_Endpoint_toString)}, + {"getInfo", reinterpret_cast(endpointGetInfo), METH_NOARGS, PyDoc_STR(IcePy_DOC_Endpoint_getInfo)}, {} /* sentinel */ }; @@ -158,7 +134,7 @@ namespace IcePy .tp_dealloc = reinterpret_cast(endpointDealloc), .tp_repr = reinterpret_cast(endpointRepr), .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, - .tp_doc = PyDoc_STR(EndpointType_doc), + .tp_doc = PyDoc_STR(IcePy_DOC_Endpoint), .tp_richcompare = reinterpret_cast(endpointCompare), .tp_methods = EndpointMethods, .tp_new = reinterpret_cast(endpointNew), diff --git a/python/modules/IcePy/EndpointInfo.cpp b/python/modules/IcePy/EndpointInfo.cpp index 55c517dc15b..45e5a556cee 100644 --- a/python/modules/IcePy/EndpointInfo.cpp +++ b/python/modules/IcePy/EndpointInfo.cpp @@ -1,42 +1,13 @@ // Copyright (c) ZeroC, Inc. #include "EndpointInfo.h" +#include "DocStrings.h" #include "Ice/Ice.h" #include "Util.h" using namespace std; using namespace IcePy; -namespace -{ - constexpr const char* endpointInfoType_doc = R"(type() -> int - -Returns the type of the endpoint. - -Returns -------- -int - The endpoint type.)"; - - constexpr const char* endpointInfoDatagram_doc = R"(datagram() -> bool - -Returns whether this endpoint is a datagram endpoint (namely, UDP). - -Returns -------- -bool - ``True`` for a UDP endpoint, ``False`` otherwise.)"; - - constexpr const char* endpointInfoSecure_doc = R"(secure() -> bool - -Returns whether this endpoint uses SSL. - -Returns -------- -bool - ``True`` for SSL and SSL-based transports, ``False`` otherwise.)"; -} - namespace IcePy { struct EndpointInfoObject @@ -168,9 +139,15 @@ opaqueEndpointInfoGetRawEncoding(EndpointInfoObject* self, PyObject* /*args*/) } static PyMethodDef EndpointInfoMethods[] = { - {"type", reinterpret_cast(endpointInfoType), METH_NOARGS, PyDoc_STR(endpointInfoType_doc)}, - {"datagram", reinterpret_cast(endpointInfoDatagram), METH_NOARGS, PyDoc_STR(endpointInfoDatagram_doc)}, - {"secure", reinterpret_cast(endpointInfoSecure), METH_NOARGS, PyDoc_STR(endpointInfoSecure_doc)}, + {"type", reinterpret_cast(endpointInfoType), METH_NOARGS, PyDoc_STR(IcePy_DOC_EndpointInfo_type)}, + {"datagram", + reinterpret_cast(endpointInfoDatagram), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_EndpointInfo_datagram)}, + {"secure", + reinterpret_cast(endpointInfoSecure), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_EndpointInfo_secure)}, {} /* sentinel */ }; @@ -178,13 +155,12 @@ static PyGetSetDef EndpointInfoGetters[] = { {"underlying", reinterpret_cast(endpointInfoGetUnderlying), nullptr, - PyDoc_STR("Ice.EndpointInfo | None: The information of the underlying endpoint or ``None`` if there's no " - "underlying endpoint."), + PyDoc_STR(IcePy_DOC_EndpointInfo_underlying), nullptr}, {"compress", reinterpret_cast(endpointInfoGetCompress), nullptr, - PyDoc_STR("bool: Specifies whether or not compression should be used if available when using this endpoint."), + PyDoc_STR(IcePy_DOC_EndpointInfo_compress), nullptr}, {} /* sentinel */ }; @@ -193,13 +169,17 @@ static PyGetSetDef IPEndpointInfoGetters[] = { {"host", reinterpret_cast(ipEndpointInfoGetHost), nullptr, - PyDoc_STR("str: The host or address configured with the endpoint."), + PyDoc_STR(IcePy_DOC_IPEndpointInfo_host), + nullptr}, + {"port", + reinterpret_cast(ipEndpointInfoGetPort), + nullptr, + PyDoc_STR(IcePy_DOC_IPEndpointInfo_port), nullptr}, - {"port", reinterpret_cast(ipEndpointInfoGetPort), nullptr, PyDoc_STR("int: The port number."), nullptr}, {"sourceAddress", reinterpret_cast(ipEndpointInfoGetSourceAddress), nullptr, - PyDoc_STR("str: The source IP address."), + PyDoc_STR(IcePy_DOC_IPEndpointInfo_sourceAddress), nullptr}, {} /* sentinel */ }; @@ -208,12 +188,12 @@ static PyGetSetDef UDPEndpointInfoGetters[] = { {"mcastInterface", reinterpret_cast(udpEndpointInfoGetMcastInterface), nullptr, - PyDoc_STR("str: The multicast interface."), + PyDoc_STR(IcePy_DOC_UDPEndpointInfo_mcastInterface), nullptr}, {"mcastTtl", reinterpret_cast(udpEndpointInfoGetMcastTtl), nullptr, - PyDoc_STR("int: The multicast time-to-live (or hops)."), + PyDoc_STR(IcePy_DOC_UDPEndpointInfo_mcastTtl), nullptr}, {} /* sentinel */ }; @@ -222,7 +202,7 @@ static PyGetSetDef WSEndpointInfoGetters[] = { {"resource", reinterpret_cast(wsEndpointInfoGetResource), nullptr, - PyDoc_STR("str: The URI configured with the endpoint."), + PyDoc_STR(IcePy_DOC_WSEndpointInfo_resource), nullptr}, {} /* sentinel */ }; @@ -231,13 +211,12 @@ static PyGetSetDef OpaqueEndpointInfoGetters[] = { {"rawBytes", reinterpret_cast(opaqueEndpointInfoGetRawBytes), nullptr, - PyDoc_STR("bytes: The raw encoding of the opaque endpoint."), + PyDoc_STR(IcePy_DOC_OpaqueEndpointInfo_rawBytes), nullptr}, {"rawEncoding", reinterpret_cast(opaqueEndpointInfoGetRawEncoding), nullptr, - PyDoc_STR( - "Ice.EncodingVersion: The encoding version of the opaque endpoint (to decode or encode the ``rawBytes``)."), + PyDoc_STR(IcePy_DOC_OpaqueEndpointInfo_rawEncoding), nullptr}, {} /* sentinel */ }; @@ -251,7 +230,7 @@ namespace IcePy .tp_basicsize = sizeof(EndpointInfoObject), .tp_dealloc = reinterpret_cast(endpointInfoDealloc), .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, - .tp_doc = PyDoc_STR("Base class for the endpoint info classes."), + .tp_doc = PyDoc_STR(IcePy_DOC_EndpointInfo), .tp_methods = EndpointInfoMethods, .tp_getset = EndpointInfoGetters, .tp_new = reinterpret_cast(endpointInfoNew), @@ -263,7 +242,7 @@ namespace IcePy .tp_basicsize = sizeof(EndpointInfoObject), .tp_dealloc = reinterpret_cast(endpointInfoDealloc), .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, - .tp_doc = PyDoc_STR("Provides access to the address details of an IP endpoint."), + .tp_doc = PyDoc_STR(IcePy_DOC_IPEndpointInfo), .tp_getset = IPEndpointInfoGetters, .tp_new = reinterpret_cast(endpointInfoNew), }; @@ -274,7 +253,7 @@ namespace IcePy .tp_basicsize = sizeof(EndpointInfoObject), .tp_dealloc = reinterpret_cast(endpointInfoDealloc), .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, - .tp_doc = PyDoc_STR("Provides access to a TCP endpoint's information."), + .tp_doc = PyDoc_STR(IcePy_DOC_TCPEndpointInfo), .tp_new = reinterpret_cast(endpointInfoNew), }; @@ -284,7 +263,7 @@ namespace IcePy .tp_basicsize = sizeof(EndpointInfoObject), .tp_dealloc = reinterpret_cast(endpointInfoDealloc), .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, - .tp_doc = PyDoc_STR("Provides access to a UDP endpoint's information."), + .tp_doc = PyDoc_STR(IcePy_DOC_UDPEndpointInfo), .tp_getset = UDPEndpointInfoGetters, .tp_new = reinterpret_cast(endpointInfoNew), }; @@ -295,7 +274,7 @@ namespace IcePy .tp_basicsize = sizeof(EndpointInfoObject), .tp_dealloc = reinterpret_cast(endpointInfoDealloc), .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, - .tp_doc = PyDoc_STR("Provides access to a WebSocket endpoint's information."), + .tp_doc = PyDoc_STR(IcePy_DOC_WSEndpointInfo), .tp_getset = WSEndpointInfoGetters, .tp_new = reinterpret_cast(endpointInfoNew), }; @@ -306,7 +285,7 @@ namespace IcePy .tp_basicsize = sizeof(EndpointInfoObject), .tp_dealloc = reinterpret_cast(endpointInfoDealloc), .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, - .tp_doc = PyDoc_STR("Provides access to an SSL endpoint's information."), + .tp_doc = PyDoc_STR(IcePy_DOC_SSLEndpointInfo), .tp_new = reinterpret_cast(endpointInfoNew), }; @@ -316,7 +295,7 @@ namespace IcePy .tp_basicsize = sizeof(EndpointInfoObject), .tp_dealloc = reinterpret_cast(endpointInfoDealloc), .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, - .tp_doc = PyDoc_STR("Provides access to the details of an opaque endpoint."), + .tp_doc = PyDoc_STR(IcePy_DOC_OpaqueEndpointInfo), .tp_getset = OpaqueEndpointInfoGetters, .tp_new = reinterpret_cast(endpointInfoNew), }; diff --git a/python/modules/IcePy/Executor.cpp b/python/modules/IcePy/Executor.cpp index b21f670688c..0b542e1265a 100644 --- a/python/modules/IcePy/Executor.cpp +++ b/python/modules/IcePy/Executor.cpp @@ -2,6 +2,7 @@ #include "Executor.h" #include "Connection.h" +#include "DocStrings.h" #include "Ice/Initialize.h" #include "Thread.h" @@ -54,6 +55,7 @@ namespace IcePy .tp_dealloc = reinterpret_cast(executorCallDealloc), .tp_call = reinterpret_cast(executorCallInvoke), .tp_flags = Py_TPFLAGS_DEFAULT, + .tp_doc = PyDoc_STR(IcePy_DOC_ExecutorCall), }; // clang-format on } diff --git a/python/modules/IcePy/ImplicitContext.cpp b/python/modules/IcePy/ImplicitContext.cpp index 60289e82f4f..219a4648d1e 100644 --- a/python/modules/IcePy/ImplicitContext.cpp +++ b/python/modules/IcePy/ImplicitContext.cpp @@ -1,6 +1,7 @@ // Copyright (c) ZeroC, Inc. #include "ImplicitContext.h" +#include "DocStrings.h" #include "Ice/ImplicitContext.h" #include "ObjectAdapter.h" #include "Proxy.h" @@ -248,24 +249,21 @@ static PyMethodDef ImplicitContextMethods[] = { {"getContext", reinterpret_cast(implicitContextGetContext), METH_NOARGS, - PyDoc_STR("getContext() -> dict[str, str]")}, + PyDoc_STR(IcePy_DOC_ImplicitContext_getContext)}, {"setContext", reinterpret_cast(implicitContextSetContext), METH_VARARGS, - PyDoc_STR("setContext(newContext: dict[str, str], /) -> None")}, + PyDoc_STR(IcePy_DOC_ImplicitContext_setContext)}, {"containsKey", reinterpret_cast(implicitContextContainsKey), METH_VARARGS, - PyDoc_STR("containsKey(key: str, /) -> bool")}, - {"get", reinterpret_cast(implicitContextGet), METH_VARARGS, PyDoc_STR("get(key: str, /) -> str")}, - {"put", - reinterpret_cast(implicitContextPut), - METH_VARARGS, - PyDoc_STR("put(key: str, value: str, /) -> str")}, + PyDoc_STR(IcePy_DOC_ImplicitContext_containsKey)}, + {"get", reinterpret_cast(implicitContextGet), METH_VARARGS, PyDoc_STR(IcePy_DOC_ImplicitContext_get)}, + {"put", reinterpret_cast(implicitContextPut), METH_VARARGS, PyDoc_STR(IcePy_DOC_ImplicitContext_put)}, {"remove", reinterpret_cast(implicitContextRemove), METH_VARARGS, - PyDoc_STR("remove(key: str, /) -> str")}, + PyDoc_STR(IcePy_DOC_ImplicitContext_remove)}, {} /* sentinel */ }; @@ -278,7 +276,7 @@ namespace IcePy .tp_basicsize = sizeof(ImplicitContextObject), .tp_dealloc = reinterpret_cast(implicitContextDealloc), .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = PyDoc_STR("IcePy.ImplicitContext"), + .tp_doc = PyDoc_STR(IcePy_DOC_ImplicitContext), .tp_richcompare = reinterpret_cast(implicitContextCompare), .tp_methods = ImplicitContextMethods, .tp_new = reinterpret_cast(implicitContextNew), diff --git a/python/modules/IcePy/Init.cpp b/python/modules/IcePy/Init.cpp index de0a010755f..a2cdf7fa0b4 100644 --- a/python/modules/IcePy/Init.cpp +++ b/python/modules/IcePy/Init.cpp @@ -4,6 +4,7 @@ #include "Communicator.h" #include "Connection.h" #include "ConnectionInfo.h" +#include "DocStrings.h" #include "Endpoint.h" #include "EndpointInfo.h" #include "Executor.h" @@ -26,156 +27,6 @@ extern "C" void IcePy_cleanup(void*); namespace { - constexpr const char* IcePy_stringVersion_doc = R"(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.)"; - - constexpr const char* IcePy_intVersion_doc = R"(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.)"; - - constexpr const char* IcePy_createProperties_doc = - R"(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.)"; - - constexpr const char* IcePy_stringToIdentity_doc = R"(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.)"; - - constexpr const char* IcePy_identityToString_doc = - R"(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.)"; - - constexpr const char* IcePy_getProcessLogger_doc = R"(getProcessLogger() -> Ice.Logger | Logger - -Gets the per-process logger. - -Returns -------- -Ice.Logger | Logger - The current per-process logger instance.)"; - - constexpr const char* IcePy_setProcessLogger_doc = R"(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.)"; - - constexpr const char* IcePy_loadSlice_doc = R"(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.)"; - - constexpr const char* IcePy_compileSlice_doc = R"(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.)"; - unsigned long mainThreadId; } @@ -183,78 +34,67 @@ static PyMethodDef methods[] = { {"stringVersion", reinterpret_cast(IcePy_stringVersion), METH_NOARGS, - PyDoc_STR(IcePy_stringVersion_doc)}, - {"intVersion", reinterpret_cast(IcePy_intVersion), METH_NOARGS, PyDoc_STR(IcePy_intVersion_doc)}, + PyDoc_STR(IcePy_DOC_stringVersion)}, + {"intVersion", reinterpret_cast(IcePy_intVersion), METH_NOARGS, PyDoc_STR(IcePy_DOC_intVersion)}, {"createProperties", reinterpret_cast(IcePy_createProperties), METH_VARARGS, - PyDoc_STR(IcePy_createProperties_doc)}, + PyDoc_STR(IcePy_DOC_createProperties)}, {"stringToIdentity", reinterpret_cast(IcePy_stringToIdentity), METH_O, - PyDoc_STR(IcePy_stringToIdentity_doc)}, + PyDoc_STR(IcePy_DOC_stringToIdentity)}, {"identityToString", reinterpret_cast(IcePy_identityToString), METH_VARARGS, - PyDoc_STR(IcePy_identityToString_doc)}, + PyDoc_STR(IcePy_DOC_identityToString)}, {"getProcessLogger", reinterpret_cast(IcePy_getProcessLogger), METH_NOARGS, - PyDoc_STR(IcePy_getProcessLogger_doc)}, + PyDoc_STR(IcePy_DOC_getProcessLogger)}, {"setProcessLogger", reinterpret_cast(IcePy_setProcessLogger), METH_VARARGS, - PyDoc_STR(IcePy_setProcessLogger_doc)}, - {"defineEnum", - reinterpret_cast(IcePy_defineEnum), - METH_VARARGS, - PyDoc_STR("defineEnum(sliceId: str, type: Type, meta: tuple, enumerators: dict, /)")}, + PyDoc_STR(IcePy_DOC_setProcessLogger)}, + {"defineEnum", reinterpret_cast(IcePy_defineEnum), METH_VARARGS, PyDoc_STR(IcePy_DOC_defineEnum)}, {"defineStruct", reinterpret_cast(IcePy_defineStruct), METH_VARARGS, - PyDoc_STR("defineStruct(sliceId: str, type: Type, meta: tuple, members: tuple, /)")}, + PyDoc_STR(IcePy_DOC_defineStruct)}, {"defineSequence", reinterpret_cast(IcePy_defineSequence), METH_VARARGS, - PyDoc_STR("defineSequence(sliceId: str, meta: tuple, elementType: TypeInfo, /)")}, + PyDoc_STR(IcePy_DOC_defineSequence)}, {"defineDictionary", reinterpret_cast(IcePy_defineDictionary), METH_VARARGS, - PyDoc_STR("defineDictionary(sliceId: str, meta: tuple, keyType: TypeInfo, valueType: TypeInfo, /)")}, + PyDoc_STR(IcePy_DOC_defineDictionary)}, {"declareProxy", reinterpret_cast(IcePy_declareProxy), METH_VARARGS, - PyDoc_STR("declareProxy(sliceId: str, /)")}, - {"defineProxy", - reinterpret_cast(IcePy_defineProxy), - METH_VARARGS, - PyDoc_STR("defineProxy(sliceId: str, proxyType: Type[ObjectPrx], /)")}, + PyDoc_STR(IcePy_DOC_declareProxy)}, + {"defineProxy", reinterpret_cast(IcePy_defineProxy), METH_VARARGS, PyDoc_STR(IcePy_DOC_defineProxy)}, {"declareValue", reinterpret_cast(IcePy_declareValue), METH_VARARGS, - PyDoc_STR("declareValue(sliceId: str, /)")}, - {"defineValue", - reinterpret_cast(IcePy_defineValue), - METH_VARARGS, - PyDoc_STR("defineValue(sliceId: str, valueType: Type[Ice.Value], compactId: int, meta: tuple, isInterface: bool, " - "baseType: Type[Ice.Value] | None, members: tuple, /)")}, + PyDoc_STR(IcePy_DOC_declareValue)}, + {"defineValue", reinterpret_cast(IcePy_defineValue), METH_VARARGS, PyDoc_STR(IcePy_DOC_defineValue)}, {"defineException", reinterpret_cast(IcePy_defineException), METH_VARARGS, - PyDoc_STR("defineException(sliceId: str, type: Type[BaseException], meta: tuple, base: Type[BaseException] | " - "None, members: tuple, /)")}, - {"loadSlice", reinterpret_cast(IcePy_loadSlice), METH_VARARGS, PyDoc_STR(IcePy_loadSlice_doc)}, + PyDoc_STR(IcePy_DOC_defineException)}, + {"loadSlice", reinterpret_cast(IcePy_loadSlice), METH_VARARGS, PyDoc_STR(IcePy_DOC_loadSlice)}, {"compileSlice", reinterpret_cast(IcePy_compileSlice), METH_VARARGS, - PyDoc_STR(IcePy_compileSlice_doc)}, + PyDoc_STR(IcePy_DOC_compileSlice)}, {} /* sentinel */ }; static struct PyModuleDef iceModule = { PyModuleDef_HEAD_INIT, "IcePy", - "The Internet Communications Engine.", + PyDoc_STR(IcePy_DOC_module), -1, methods, nullptr, diff --git a/python/modules/IcePy/Logger.cpp b/python/modules/IcePy/Logger.cpp index c70c532e813..5cc0eae0c95 100644 --- a/python/modules/IcePy/Logger.cpp +++ b/python/modules/IcePy/Logger.cpp @@ -1,6 +1,7 @@ // Copyright (c) ZeroC, Inc. #include "Logger.h" +#include "DocStrings.h" #include "Ice/Initialize.h" #include "Thread.h" @@ -310,21 +311,15 @@ loggerCloneWithPrefix(LoggerObject* self, PyObject* args) } static PyMethodDef LoggerMethods[] = { - {"print", reinterpret_cast(loggerPrint), METH_VARARGS, PyDoc_STR("print(message: str, /) -> None")}, - {"trace", - reinterpret_cast(loggerTrace), - METH_VARARGS, - PyDoc_STR("trace(category: str, message: str, /) -> None")}, - {"warning", - reinterpret_cast(loggerWarning), - METH_VARARGS, - PyDoc_STR("warning(message: str, /) -> None")}, - {"error", reinterpret_cast(loggerError), METH_VARARGS, PyDoc_STR("error(message: str, /) -> None")}, - {"getPrefix", reinterpret_cast(loggerGetPrefix), METH_NOARGS, PyDoc_STR("getPrefix() -> str")}, + {"print", reinterpret_cast(loggerPrint), METH_VARARGS, PyDoc_STR(IcePy_DOC_Logger_print)}, + {"trace", reinterpret_cast(loggerTrace), METH_VARARGS, PyDoc_STR(IcePy_DOC_Logger_trace)}, + {"warning", reinterpret_cast(loggerWarning), METH_VARARGS, PyDoc_STR(IcePy_DOC_Logger_warning)}, + {"error", reinterpret_cast(loggerError), METH_VARARGS, PyDoc_STR(IcePy_DOC_Logger_error)}, + {"getPrefix", reinterpret_cast(loggerGetPrefix), METH_NOARGS, PyDoc_STR(IcePy_DOC_Logger_getPrefix)}, {"cloneWithPrefix", reinterpret_cast(loggerCloneWithPrefix), METH_VARARGS, - PyDoc_STR("cloneWithPrefix(prefix: str, /) -> Logger")}, + PyDoc_STR(IcePy_DOC_Logger_cloneWithPrefix)}, {} /* sentinel */ }; @@ -337,7 +332,7 @@ namespace IcePy .tp_basicsize = sizeof(LoggerObject), .tp_dealloc = reinterpret_cast(loggerDealloc), .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = PyDoc_STR("IcePy.Logger"), + .tp_doc = PyDoc_STR(IcePy_DOC_Logger), .tp_methods = LoggerMethods, .tp_new = reinterpret_cast(loggerNew), }; diff --git a/python/modules/IcePy/ObjectAdapter.cpp b/python/modules/IcePy/ObjectAdapter.cpp index 975303f7780..2bf8ec7b3d5 100644 --- a/python/modules/IcePy/ObjectAdapter.cpp +++ b/python/modules/IcePy/ObjectAdapter.cpp @@ -3,6 +3,7 @@ #include "ObjectAdapter.h" #include "Communicator.h" #include "Current.h" +#include "DocStrings.h" #include "Endpoint.h" #include "Ice/Communicator.h" #include "Ice/LocalExceptions.h" @@ -1450,127 +1451,124 @@ adapterSetPublishedEndpoints(ObjectAdapterObject* self, PyObject* args) } static PyMethodDef AdapterMethods[] = { - {"getName", reinterpret_cast(adapterGetName), METH_NOARGS, PyDoc_STR("getName() -> str")}, + {"getName", reinterpret_cast(adapterGetName), METH_NOARGS, PyDoc_STR(IcePy_DOC_ObjectAdapter_getName)}, {"getCommunicator", reinterpret_cast(adapterGetCommunicator), METH_NOARGS, - PyDoc_STR("getCommunicator() -> Communicator")}, - {"activate", reinterpret_cast(adapterActivate), METH_NOARGS, PyDoc_STR("activate() -> None")}, - {"hold", reinterpret_cast(adapterHold), METH_NOARGS, PyDoc_STR("hold() -> None")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_getCommunicator)}, + {"activate", + reinterpret_cast(adapterActivate), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_ObjectAdapter_activate)}, + {"hold", reinterpret_cast(adapterHold), METH_NOARGS, PyDoc_STR(IcePy_DOC_ObjectAdapter_hold)}, {"waitForHold", reinterpret_cast(adapterWaitForHold), METH_VARARGS, - PyDoc_STR("waitForHold(timeout: int, /) -> bool")}, - {"deactivate", reinterpret_cast(adapterDeactivate), METH_NOARGS, PyDoc_STR("deactivate() -> None")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_waitForHold)}, + {"deactivate", + reinterpret_cast(adapterDeactivate), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_ObjectAdapter_deactivate)}, {"waitForDeactivate", reinterpret_cast(adapterWaitForDeactivate), METH_VARARGS, - PyDoc_STR("waitForDeactivate(timeout: int, /) -> bool")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_waitForDeactivate)}, {"isDeactivated", reinterpret_cast(adapterIsDeactivated), METH_NOARGS, - PyDoc_STR("isDeactivated() -> bool")}, - {"destroy", reinterpret_cast(adapterDestroy), METH_NOARGS, PyDoc_STR("destroy() -> None")}, - {"add", - reinterpret_cast(adapterAdd), - METH_VARARGS, - PyDoc_STR("add(servant: Ice.Object, id: Ice.Identity, /) -> Ice.ObjectPrx")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_isDeactivated)}, + {"destroy", reinterpret_cast(adapterDestroy), METH_NOARGS, PyDoc_STR(IcePy_DOC_ObjectAdapter_destroy)}, + {"add", reinterpret_cast(adapterAdd), METH_VARARGS, PyDoc_STR(IcePy_DOC_ObjectAdapter_add)}, {"addFacet", reinterpret_cast(adapterAddFacet), METH_VARARGS, - PyDoc_STR("addFacet(servant: Ice.Object, id: Ice.Identity, facet: str, /) -> Ice.ObjectPrx")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_addFacet)}, {"addWithUUID", reinterpret_cast(adapterAddWithUUID), METH_VARARGS, - PyDoc_STR("addWithUUID(servant: Ice.Object, /) -> Ice.ObjectPrx")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_addWithUUID)}, {"addFacetWithUUID", reinterpret_cast(adapterAddFacetWithUUID), METH_VARARGS, - PyDoc_STR("addFacetWithUUID(servant: Ice.Object, facet: str, /) -> Ice.ObjectPrx")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_addFacetWithUUID)}, {"addDefaultServant", reinterpret_cast(adapterAddDefaultServant), METH_VARARGS, - PyDoc_STR("addDefaultServant(servant: Ice.Object, category: str, /) -> None")}, - {"remove", - reinterpret_cast(adapterRemove), - METH_VARARGS, - PyDoc_STR("remove(id: Ice.Identity, /) -> Ice.Object")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_addDefaultServant)}, + {"remove", reinterpret_cast(adapterRemove), METH_VARARGS, PyDoc_STR(IcePy_DOC_ObjectAdapter_remove)}, {"removeFacet", reinterpret_cast(adapterRemoveFacet), METH_VARARGS, - PyDoc_STR("removeFacet(id: Ice.Identity, facet: str, /) -> Ice.Object")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_removeFacet)}, {"removeAllFacets", reinterpret_cast(adapterRemoveAllFacets), METH_VARARGS, - PyDoc_STR("removeAllFacets(id: Ice.Identity, /) -> dict[str, Ice.Object]")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_removeAllFacets)}, {"removeDefaultServant", reinterpret_cast(adapterRemoveDefaultServant), METH_VARARGS, - PyDoc_STR("removeDefaultServant(category: str, /) -> Ice.Object")}, - {"find", - reinterpret_cast(adapterFind), - METH_VARARGS, - PyDoc_STR("find(identity: Ice.Identity, /) -> Ice.Object | None")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_removeDefaultServant)}, + {"find", reinterpret_cast(adapterFind), METH_VARARGS, PyDoc_STR(IcePy_DOC_ObjectAdapter_find)}, {"findFacet", reinterpret_cast(adapterFindFacet), METH_VARARGS, - PyDoc_STR("findFacet(id: Ice.Identity, facet: str, /) -> Ice.Object | None")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_findFacet)}, {"findAllFacets", reinterpret_cast(adapterFindAllFacets), METH_VARARGS, - PyDoc_STR("findAllFacets(id: Ice.Identity, /) -> dict[str, Ice.Object]")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_findAllFacets)}, {"findByProxy", reinterpret_cast(adapterFindByProxy), METH_VARARGS, - PyDoc_STR("findByProxy(proxy: Ice.ObjectPrx, /) -> Ice.Object | None")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_findByProxy)}, {"findDefaultServant", reinterpret_cast(adapterFindDefaultServant), METH_VARARGS, - PyDoc_STR("findDefaultServant(category: str, /) -> Ice.Object | None")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_findDefaultServant)}, {"addServantLocator", reinterpret_cast(adapterAddServantLocator), METH_VARARGS, - PyDoc_STR("addServantLocator(locator: Ice.ServantLocator, category: str, /) -> None")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_addServantLocator)}, {"removeServantLocator", reinterpret_cast(adapterRemoveServantLocator), METH_VARARGS, - PyDoc_STR("removeServantLocator(category: str, /) -> Ice.ServantLocator")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_removeServantLocator)}, {"findServantLocator", reinterpret_cast(adapterFindServantLocator), METH_VARARGS, - PyDoc_STR("findServantLocator(category: str, /) -> Ice.ServantLocator | None")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_findServantLocator)}, {"createProxy", reinterpret_cast(adapterCreateProxy), METH_VARARGS, - PyDoc_STR("createProxy(identity: Ice.Identity, /) -> Ice.ObjectPrx")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_createProxy)}, {"createDirectProxy", reinterpret_cast(adapterCreateDirectProxy), METH_VARARGS, - PyDoc_STR("createDirectProxy(identity: Ice.Identity, /) -> Ice.ObjectPrx")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_createDirectProxy)}, {"createIndirectProxy", reinterpret_cast(adapterCreateIndirectProxy), METH_VARARGS, - PyDoc_STR("createIndirectProxy(identity: Ice.Identity, /) -> Ice.ObjectPrx")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_createIndirectProxy)}, {"setLocator", reinterpret_cast(adapterSetLocator), METH_VARARGS, - PyDoc_STR("setLocator(locator: Ice.LocatorPrx | None, /) -> None")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_setLocator)}, {"getLocator", reinterpret_cast(adapterGetLocator), METH_NOARGS, - PyDoc_STR("getLocator() -> Ice.LocatorPrx | None")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_getLocator)}, {"getEndpoints", reinterpret_cast(adapterGetEndpoints), METH_NOARGS, - PyDoc_STR("getEndpoints() -> tuple[Endpoint, ...]")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_getEndpoints)}, {"getPublishedEndpoints", reinterpret_cast(adapterGetPublishedEndpoints), METH_NOARGS, - PyDoc_STR("getPublishedEndpoints() -> tuple[Endpoint, ...]")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_getPublishedEndpoints)}, {"setPublishedEndpoints", reinterpret_cast(adapterSetPublishedEndpoints), METH_VARARGS, - PyDoc_STR("setPublishedEndpoints(newEndpoints: tuple[Endpoint, ...] | list[Endpoint], /) -> None")}, + PyDoc_STR(IcePy_DOC_ObjectAdapter_setPublishedEndpoints)}, {} /* sentinel */ }; @@ -1583,7 +1581,7 @@ namespace IcePy .tp_basicsize = sizeof(ObjectAdapterObject), .tp_dealloc = reinterpret_cast(adapterDealloc), .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = PyDoc_STR("IcePy.ObjectAdapter"), + .tp_doc = PyDoc_STR(IcePy_DOC_ObjectAdapter), .tp_methods = AdapterMethods, .tp_new = reinterpret_cast(adapterNew), }; diff --git a/python/modules/IcePy/Operation.cpp b/python/modules/IcePy/Operation.cpp index 4667c2fa63e..aa0620c3469 100644 --- a/python/modules/IcePy/Operation.cpp +++ b/python/modules/IcePy/Operation.cpp @@ -5,6 +5,7 @@ #include "Communicator.h" #include "Connection.h" #include "Current.h" +#include "DocStrings.h" #include "Future.h" #include "Ice/Communicator.h" #include "Ice/Initialize.h" @@ -841,18 +842,15 @@ IcePy::Operation::convertParam(PyObject* p, Py_ssize_t pos) } static PyMethodDef OperationMethods[] = { - {"invoke", - reinterpret_cast(operationInvoke), - METH_VARARGS, - PyDoc_STR("invoke(proxy: ObjectPrx, args: tuple, /) -> Any")}, + {"invoke", reinterpret_cast(operationInvoke), METH_VARARGS, PyDoc_STR(IcePy_DOC_Operation_invoke)}, {"invokeAsync", reinterpret_cast(operationInvokeAsync), METH_VARARGS, - PyDoc_STR("invokeAsync(proxy: ObjectPrx, args: tuple, /) -> Awaitable[Any]")}, + PyDoc_STR(IcePy_DOC_Operation_invokeAsync)}, {"deprecate", reinterpret_cast(operationDeprecate), METH_VARARGS, - PyDoc_STR("deprecate(reason: str, /)")}, + PyDoc_STR(IcePy_DOC_Operation_deprecate)}, {} /* sentinel */ }; @@ -860,16 +858,19 @@ static PyMethodDef DispatchCallbackMethods[] = { {"response", reinterpret_cast(dispatchCallbackResponse), METH_VARARGS, - PyDoc_STR("response(result: Any, /) -> None")}, + PyDoc_STR(IcePy_DOC_DispatchCallback_response)}, {"exception", reinterpret_cast(dispatchCallbackException), METH_VARARGS, - PyDoc_STR("exception(exception: BaseException, /) -> None")}, + PyDoc_STR(IcePy_DOC_DispatchCallback_exception)}, {} /* sentinel */ }; static PyMethodDef AsyncInvocationContextMethods[] = { - {"cancel", reinterpret_cast(asyncInvocationContextCancel), METH_NOARGS, PyDoc_STR("cancel() -> None")}, + {"cancel", + reinterpret_cast(asyncInvocationContextCancel), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_AsyncInvocationContext_cancel)}, {} /* sentinel */ }; @@ -882,7 +883,7 @@ namespace IcePy .tp_basicsize = sizeof(OperationObject), .tp_dealloc = reinterpret_cast(operationDealloc), .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = PyDoc_STR("IcePy.Operation"), + .tp_doc = PyDoc_STR(IcePy_DOC_Operation), .tp_methods = OperationMethods, .tp_init = reinterpret_cast(operationInit), .tp_new = reinterpret_cast(operationNew), @@ -894,7 +895,7 @@ namespace IcePy .tp_basicsize = sizeof(DispatchCallbackObject), .tp_dealloc = reinterpret_cast(dispatchCallbackDealloc), .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = PyDoc_STR("IcePy.DispatchCallback"), + .tp_doc = PyDoc_STR(IcePy_DOC_DispatchCallback), .tp_methods = DispatchCallbackMethods, .tp_new = reinterpret_cast(dispatchCallbackNew), }; @@ -905,7 +906,7 @@ namespace IcePy .tp_basicsize = sizeof(AsyncInvocationContextObject), .tp_dealloc = reinterpret_cast(asyncInvocationContextDealloc), .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = PyDoc_STR("IcePy.AsyncInvocationContext"), + .tp_doc = PyDoc_STR(IcePy_DOC_AsyncInvocationContext), .tp_methods = AsyncInvocationContextMethods, .tp_new = reinterpret_cast(asyncInvocationContextNew), }; diff --git a/python/modules/IcePy/Properties.cpp b/python/modules/IcePy/Properties.cpp index 1b113a2f910..31070afd0b3 100644 --- a/python/modules/IcePy/Properties.cpp +++ b/python/modules/IcePy/Properties.cpp @@ -1,6 +1,7 @@ // Copyright (c) ZeroC, Inc. #include "Properties.h" +#include "DocStrings.h" #include "Ice/Initialize.h" #include "Ice/Properties.h" #include "Util.h" @@ -687,61 +688,61 @@ static PyMethodDef PropertyMethods[] = { {"getProperty", reinterpret_cast(propertiesGetProperty), METH_VARARGS, - PyDoc_STR("getProperty(key: str, /) -> str")}, + PyDoc_STR(IcePy_DOC_Properties_getProperty)}, {"getIceProperty", reinterpret_cast(propertiesGetIceProperty), METH_VARARGS, - PyDoc_STR("getIceProperty(key: str, /) -> str")}, + PyDoc_STR(IcePy_DOC_Properties_getIceProperty)}, {"getPropertyWithDefault", reinterpret_cast(propertiesGetPropertyWithDefault), METH_VARARGS, - PyDoc_STR("getPropertyWithDefault(key: str, value: str, /) -> str")}, + PyDoc_STR(IcePy_DOC_Properties_getPropertyWithDefault)}, {"getPropertyAsInt", reinterpret_cast(propertiesGetPropertyAsInt), METH_VARARGS, - PyDoc_STR("getPropertyAsInt(key: str, /) -> int")}, + PyDoc_STR(IcePy_DOC_Properties_getPropertyAsInt)}, {"getIcePropertyAsInt", reinterpret_cast(propertiesGetIcePropertyAsInt), METH_VARARGS, - PyDoc_STR("getIcePropertyAsInt(key: str, /) -> int")}, + PyDoc_STR(IcePy_DOC_Properties_getIcePropertyAsInt)}, {"getPropertyAsIntWithDefault", reinterpret_cast(propertiesGetPropertyAsIntWithDefault), METH_VARARGS, - PyDoc_STR("getPropertyAsIntWithDefault(key: str, value: int, /) -> int")}, + PyDoc_STR(IcePy_DOC_Properties_getPropertyAsIntWithDefault)}, {"getPropertyAsList", reinterpret_cast(propertiesGetPropertyAsList), METH_VARARGS, - PyDoc_STR("getPropertyAsList(key: str, /) -> list[str]")}, + PyDoc_STR(IcePy_DOC_Properties_getPropertyAsList)}, {"getIcePropertyAsList", reinterpret_cast(propertiesGetIcePropertyAsList), METH_VARARGS, - PyDoc_STR("getIcePropertyAsList(key: str, /) -> list[str]")}, + PyDoc_STR(IcePy_DOC_Properties_getIcePropertyAsList)}, {"getPropertyAsListWithDefault", reinterpret_cast(propertiesGetPropertyAsListWithDefault), METH_VARARGS, - PyDoc_STR("getPropertyAsListWithDefault(key: str, value: list[str], /) -> list[str]")}, + PyDoc_STR(IcePy_DOC_Properties_getPropertyAsListWithDefault)}, {"getPropertiesForPrefix", reinterpret_cast(propertiesGetPropertiesForPrefix), METH_VARARGS, - PyDoc_STR("getPropertiesForPrefix(prefix: str, /) -> dict[str, str]")}, + PyDoc_STR(IcePy_DOC_Properties_getPropertiesForPrefix)}, {"setProperty", reinterpret_cast(propertiesSetProperty), METH_VARARGS, - PyDoc_STR("setProperty(key: str, value: str, /) -> None")}, + PyDoc_STR(IcePy_DOC_Properties_setProperty)}, {"getCommandLineOptions", reinterpret_cast(propertiesGetCommandLineOptions), METH_NOARGS, - PyDoc_STR("getCommandLineOptions() -> list[str]")}, + PyDoc_STR(IcePy_DOC_Properties_getCommandLineOptions)}, {"parseCommandLineOptions", reinterpret_cast(propertiesParseCommandLineOptions), METH_VARARGS, - PyDoc_STR("parseCommandLineOptions(prefix: str, options: list[str], /) -> list[str]")}, + PyDoc_STR(IcePy_DOC_Properties_parseCommandLineOptions)}, {"parseIceCommandLineOptions", reinterpret_cast(propertiesParseIceCommandLineOptions), METH_VARARGS, - PyDoc_STR("parseIceCommandLineOptions(options: list[str], /) -> list[str]")}, - {"load", reinterpret_cast(propertiesLoad), METH_VARARGS, PyDoc_STR("load(file: str, /) -> None")}, - {"clone", reinterpret_cast(propertiesClone), METH_NOARGS, PyDoc_STR("clone() -> Properties")}, + PyDoc_STR(IcePy_DOC_Properties_parseIceCommandLineOptions)}, + {"load", reinterpret_cast(propertiesLoad), METH_VARARGS, PyDoc_STR(IcePy_DOC_Properties_load)}, + {"clone", reinterpret_cast(propertiesClone), METH_NOARGS, PyDoc_STR(IcePy_DOC_Properties_clone)}, {} /* sentinel */ }; @@ -755,7 +756,7 @@ namespace IcePy .tp_dealloc = reinterpret_cast(propertiesDealloc), .tp_str = reinterpret_cast(propertiesStr), .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = PyDoc_STR("IcePy.Properties"), + .tp_doc = PyDoc_STR(IcePy_DOC_Properties), .tp_methods = PropertyMethods, .tp_init = reinterpret_cast(propertiesInit), .tp_new = reinterpret_cast(propertiesNew), diff --git a/python/modules/IcePy/PropertiesAdmin.cpp b/python/modules/IcePy/PropertiesAdmin.cpp index 3ffb335eb31..42915098db1 100644 --- a/python/modules/IcePy/PropertiesAdmin.cpp +++ b/python/modules/IcePy/PropertiesAdmin.cpp @@ -1,6 +1,7 @@ // Copyright (c) ZeroC, Inc. #include "PropertiesAdmin.h" +#include "DocStrings.h" #include "Ice/DisableWarnings.h" #include "Thread.h" #include "Util.h" @@ -10,29 +11,6 @@ using namespace std; using namespace IcePy; -namespace -{ - constexpr const char* nativePropertiesAdminAddUpdateCB_doc = - R"(addUpdateCallback(callback: Callable[[dict[str, str]], None], /) -> None - -Registers an update callback that will be invoked when a property update occurs. - -Parameters ----------- -callback : Callable[[dict[str, str]], None] - The callback.)"; - - constexpr const char* nativePropertiesAdminRemoveUpdateCB_doc = - R"(removeUpdateCallback(callback: Callable[[dict[str, str]], None], /) -> None - -Removes a previously registered update callback. - -Parameters ----------- -callback : Callable[[dict[str, str]], None] - The callback to remove.)"; -} - namespace IcePy { struct NativePropertiesAdminObject @@ -143,11 +121,11 @@ static PyMethodDef NativePropertiesAdminMethods[] = { {"addUpdateCallback", reinterpret_cast(nativePropertiesAdminAddUpdateCB), METH_VARARGS, - PyDoc_STR(nativePropertiesAdminAddUpdateCB_doc)}, + PyDoc_STR(IcePy_DOC_NativePropertiesAdmin_addUpdateCallback)}, {"removeUpdateCallback", reinterpret_cast(nativePropertiesAdminRemoveUpdateCB), METH_VARARGS, - PyDoc_STR(nativePropertiesAdminRemoveUpdateCB_doc)}, + PyDoc_STR(IcePy_DOC_NativePropertiesAdmin_removeUpdateCallback)}, {} /* sentinel */ }; @@ -160,7 +138,7 @@ namespace IcePy .tp_basicsize = sizeof(NativePropertiesAdminObject), .tp_dealloc = reinterpret_cast(nativePropertiesAdminDealloc), .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = PyDoc_STR("The default implementation of the 'Properties' admin facet."), + .tp_doc = PyDoc_STR(IcePy_DOC_NativePropertiesAdmin), .tp_methods = NativePropertiesAdminMethods, .tp_new = reinterpret_cast(nativePropertiesAdminNew), }; diff --git a/python/modules/IcePy/Proxy.cpp b/python/modules/IcePy/Proxy.cpp index 6c47d0ea612..9f201ad67a2 100644 --- a/python/modules/IcePy/Proxy.cpp +++ b/python/modules/IcePy/Proxy.cpp @@ -3,6 +3,7 @@ #include "Proxy.h" #include "Communicator.h" #include "Connection.h" +#include "DocStrings.h" #include "Endpoint.h" #include "Future.h" #include "Ice/Communicator.h" @@ -1248,189 +1249,205 @@ static PyMethodDef ProxyMethods[] = { {"ice_getCommunicator", reinterpret_cast(proxyIceGetCommunicator), METH_NOARGS, - PyDoc_STR("ice_getCommunicator() -> Ice.Communicator")}, - {"ice_toString", reinterpret_cast(proxyRepr), METH_NOARGS, PyDoc_STR("ice_toString() -> str")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_getCommunicator)}, + {"ice_toString", + reinterpret_cast(proxyRepr), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_toString)}, {"ice_getIdentity", reinterpret_cast(proxyIceGetIdentity), METH_NOARGS, - PyDoc_STR("ice_getIdentity() -> Ice.Identity")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_getIdentity)}, {"ice_identity", reinterpret_cast(proxyIceIdentity), METH_VARARGS, - PyDoc_STR("ice_identity(newIdentity: Ice.Identity, /) -> Ice.ObjectPrx")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_identity)}, {"ice_getContext", reinterpret_cast(proxyIceGetContext), METH_NOARGS, - PyDoc_STR("ice_getContext() -> dict[str, str]")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_getContext)}, {"ice_context", reinterpret_cast(proxyIceContext), METH_VARARGS, - PyDoc_STR("ice_context(new_context: dict[str, str], /) -> Self")}, - {"ice_getFacet", reinterpret_cast(proxyIceGetFacet), METH_NOARGS, PyDoc_STR("ice_getFacet() -> str")}, - {"ice_facet", - reinterpret_cast(proxyIceFacet), - METH_VARARGS, - PyDoc_STR("ice_facet(new_facet: str, /) -> Ice.ObjectPrx")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_context)}, + {"ice_getFacet", + reinterpret_cast(proxyIceGetFacet), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_getFacet)}, + {"ice_facet", reinterpret_cast(proxyIceFacet), METH_VARARGS, PyDoc_STR(IcePy_DOC_ObjectPrx_ice_facet)}, {"ice_getAdapterId", reinterpret_cast(proxyIceGetAdapterId), METH_NOARGS, - PyDoc_STR("ice_getAdapterId() -> str")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_getAdapterId)}, {"ice_adapterId", reinterpret_cast(proxyIceAdapterId), METH_VARARGS, - PyDoc_STR("ice_adapterId(newAdapterId: str, /) -> Self")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_adapterId)}, {"ice_getEndpoints", reinterpret_cast(proxyIceGetEndpoints), METH_NOARGS, - PyDoc_STR("ice_getEndpoints() -> tuple[Endpoint, ...]")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_getEndpoints)}, {"ice_endpoints", reinterpret_cast(proxyIceEndpoints), METH_VARARGS, - PyDoc_STR("ice_endpoints(newEndpoints: tuple[Endpoint, ...] | list[Endpoint], /) -> Self")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_endpoints)}, {"ice_getLocatorCacheTimeout", reinterpret_cast(proxyIceGetLocatorCacheTimeout), METH_NOARGS, - PyDoc_STR("ice_getLocatorCacheTimeout() -> int")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_getLocatorCacheTimeout)}, {"ice_getInvocationTimeout", reinterpret_cast(proxyIceGetInvocationTimeout), METH_NOARGS, - PyDoc_STR("ice_getInvocationTimeout() -> int")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_getInvocationTimeout)}, {"ice_getConnectionId", reinterpret_cast(proxyIceGetConnectionId), METH_NOARGS, - PyDoc_STR("ice_getConnectionId() -> str")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_getConnectionId)}, {"ice_isCollocationOptimized", reinterpret_cast(proxyIceIsCollocationOptimized), METH_NOARGS, - PyDoc_STR("ice_isCollocationOptimized() -> bool")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_isCollocationOptimized)}, {"ice_collocationOptimized", reinterpret_cast(proxyIceCollocationOptimized), METH_VARARGS, - PyDoc_STR("ice_collocationOptimized(collocated: bool, /) -> Self")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_collocationOptimized)}, {"ice_locatorCacheTimeout", reinterpret_cast(proxyIceLocatorCacheTimeout), METH_VARARGS, - PyDoc_STR("ice_locatorCacheTimeout(timeout: int, /) -> Self")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_locatorCacheTimeout)}, {"ice_invocationTimeout", reinterpret_cast(proxyIceInvocationTimeout), METH_VARARGS, - PyDoc_STR("ice_invocationTimeout(timeout: int, /) -> Self")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_invocationTimeout)}, {"ice_isConnectionCached", reinterpret_cast(proxyIceIsConnectionCached), METH_NOARGS, - PyDoc_STR("ice_isConnectionCached() -> bool")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_isConnectionCached)}, {"ice_connectionCached", reinterpret_cast(proxyIceConnectionCached), METH_VARARGS, - PyDoc_STR("ice_connectionCached(newCache: bool, /) -> Self")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_connectionCached)}, {"ice_getEndpointSelection", reinterpret_cast(proxyIceGetEndpointSelection), METH_NOARGS, - PyDoc_STR("ice_getEndpointSelection() -> Ice.EndpointSelectionType")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_getEndpointSelection)}, {"ice_endpointSelection", reinterpret_cast(proxyIceEndpointSelection), METH_VARARGS, - PyDoc_STR("ice_endpointSelection(newType: Ice.EndpointSelectionType, /) -> Self")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_endpointSelection)}, {"ice_getEncodingVersion", reinterpret_cast(proxyIceGetEncodingVersion), METH_NOARGS, - PyDoc_STR("ice_getEncodingVersion() -> Ice.EncodingVersion")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_getEncodingVersion)}, {"ice_encodingVersion", reinterpret_cast(proxyIceEncodingVersion), METH_VARARGS, - PyDoc_STR("ice_encodingVersion(version: Ice.EncodingVersion, /) -> Self")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_encodingVersion)}, {"ice_getRouter", reinterpret_cast(proxyIceGetRouter), METH_NOARGS, - PyDoc_STR("ice_getRouter() -> Ice.RouterPrx | None")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_getRouter)}, {"ice_router", reinterpret_cast(proxyIceRouter), METH_VARARGS, - PyDoc_STR("ice_router(router: Ice.RouterPrx | None, /) -> Self")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_router)}, {"ice_getLocator", reinterpret_cast(proxyIceGetLocator), METH_NOARGS, - PyDoc_STR("ice_getLocator() -> Ice.LocatorPrx | None")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_getLocator)}, {"ice_locator", reinterpret_cast(proxyIceLocator), METH_VARARGS, - PyDoc_STR("ice_locator(locator: Ice.LocatorPrx | None, /) -> Self")}, - {"ice_twoway", reinterpret_cast(proxyIceTwoway), METH_NOARGS, PyDoc_STR("ice_twoway() -> Self")}, - {"ice_isTwoway", reinterpret_cast(proxyIceIsTwoway), METH_NOARGS, PyDoc_STR("ice_isTwoway() -> bool")}, - {"ice_oneway", reinterpret_cast(proxyIceOneway), METH_NOARGS, PyDoc_STR("ice_oneway() -> Self")}, - {"ice_isOneway", reinterpret_cast(proxyIceIsOneway), METH_NOARGS, PyDoc_STR("ice_isOneway() -> bool")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_locator)}, + {"ice_twoway", + reinterpret_cast(proxyIceTwoway), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_twoway)}, + {"ice_isTwoway", + reinterpret_cast(proxyIceIsTwoway), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_isTwoway)}, + {"ice_oneway", + reinterpret_cast(proxyIceOneway), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_oneway)}, + {"ice_isOneway", + reinterpret_cast(proxyIceIsOneway), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_isOneway)}, {"ice_batchOneway", reinterpret_cast(proxyIceBatchOneway), METH_NOARGS, - PyDoc_STR("ice_batchOneway() -> Self")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_batchOneway)}, {"ice_isBatchOneway", reinterpret_cast(proxyIceIsBatchOneway), METH_NOARGS, - PyDoc_STR("ice_isBatchOneway() -> bool")}, - {"ice_datagram", reinterpret_cast(proxyIceDatagram), METH_NOARGS, PyDoc_STR("ice_datagram() -> Self")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_isBatchOneway)}, + {"ice_datagram", + reinterpret_cast(proxyIceDatagram), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_datagram)}, {"ice_isDatagram", reinterpret_cast(proxyIceIsDatagram), METH_NOARGS, - PyDoc_STR("ice_isDatagram() -> bool")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_isDatagram)}, {"ice_batchDatagram", reinterpret_cast(proxyIceBatchDatagram), METH_NOARGS, - PyDoc_STR("ice_batchDatagram() -> Self")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_batchDatagram)}, {"ice_isBatchDatagram", reinterpret_cast(proxyIceIsBatchDatagram), METH_NOARGS, - PyDoc_STR("ice_isBatchDatagram() -> bool")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_isBatchDatagram)}, {"ice_compress", reinterpret_cast(proxyIceCompress), METH_VARARGS, - PyDoc_STR("ice_compress(compress: bool, /) -> Self")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_compress)}, {"ice_getCompress", reinterpret_cast(proxyIceGetCompress), METH_VARARGS, - PyDoc_STR("ice_getCompress() -> bool | None")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_getCompress)}, {"ice_connectionId", reinterpret_cast(proxyIceConnectionId), METH_VARARGS, - PyDoc_STR("ice_connectionId(connectionId: str, /) -> Self")}, - {"ice_fixed", - reinterpret_cast(proxyIceFixed), - METH_VARARGS, - PyDoc_STR("ice_fixed(connection: Ice.Connection, /) -> Self")}, - {"ice_isFixed", reinterpret_cast(proxyIceIsFixed), METH_NOARGS, PyDoc_STR("ice_isFixed() -> bool")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_connectionId)}, + {"ice_fixed", reinterpret_cast(proxyIceFixed), METH_VARARGS, PyDoc_STR(IcePy_DOC_ObjectPrx_ice_fixed)}, + {"ice_isFixed", + reinterpret_cast(proxyIceIsFixed), + METH_NOARGS, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_isFixed)}, {"ice_getConnection", reinterpret_cast(proxyIceGetConnection), METH_NOARGS, - PyDoc_STR("ice_getConnection() -> Ice.Connection | None")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_getConnection)}, {"ice_getConnectionAsync", reinterpret_cast(proxyIceGetConnectionAsync), METH_NOARGS, - PyDoc_STR("ice_getConnectionAsync() -> Awaitable[Ice.Connection | None]")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_getConnectionAsync)}, {"ice_getCachedConnection", reinterpret_cast(proxyIceGetCachedConnection), METH_NOARGS, - PyDoc_STR("ice_getCachedConnection() -> Ice.Connection | None")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_getCachedConnection)}, {"ice_flushBatchRequests", reinterpret_cast(proxyIceFlushBatchRequests), METH_NOARGS, - PyDoc_STR("ice_flushBatchRequests() -> None")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_flushBatchRequests)}, {"ice_flushBatchRequestsAsync", reinterpret_cast(proxyIceFlushBatchRequestsAsync), METH_NOARGS, - PyDoc_STR("ice_flushBatchRequestsAsync() -> Awaitable[None]")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_flushBatchRequestsAsync)}, {"ice_invoke", reinterpret_cast(proxyIceInvoke), METH_VARARGS | METH_KEYWORDS, - PyDoc_STR("ice_invoke(operation: str, mode: Ice.OperationMode, inParams: bytes, " - "ctx: dict[str, str] | None = None) -> tuple[bool, bytes]")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_invoke)}, {"ice_invokeAsync", reinterpret_cast(proxyIceInvokeAsync), METH_VARARGS | METH_KEYWORDS, - PyDoc_STR("ice_invokeAsync(operation: str, mode: Ice.OperationMode, inParams: bytes, " - "ctx: dict[str, str] | None = None) -> Awaitable[tuple[bool, bytes]]")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_ice_invokeAsync)}, {"newProxy", reinterpret_cast(proxyNewProxy), METH_VARARGS | METH_STATIC, - PyDoc_STR("newProxy(type: Type[T], proxy: Ice.ObjectPrx, /) -> T")}, + PyDoc_STR(IcePy_DOC_ObjectPrx_newProxy)}, {} /* sentinel */ }; @@ -1445,7 +1462,7 @@ namespace IcePy .tp_repr = reinterpret_cast(proxyRepr), .tp_hash = reinterpret_cast(proxyHash), .tp_flags = Py_TPFLAGS_BASETYPE, - .tp_doc = PyDoc_STR("IcePy.ObjectPrx"), + .tp_doc = PyDoc_STR(IcePy_DOC_ObjectPrx), .tp_richcompare = reinterpret_cast(proxyCompare), .tp_methods = ProxyMethods, .tp_init = reinterpret_cast(proxyInit), diff --git a/python/modules/IcePy/Types.cpp b/python/modules/IcePy/Types.cpp index 3d96713ec24..8dca8ab720c 100644 --- a/python/modules/IcePy/Types.cpp +++ b/python/modules/IcePy/Types.cpp @@ -7,6 +7,7 @@ #include "Types.h" #include "Current.h" +#include "DocStrings.h" #include "Ice/DisableWarnings.h" #include "Ice/InputStream.h" #include "Ice/LocalExceptions.h" @@ -3378,7 +3379,7 @@ namespace IcePy .tp_basicsize = sizeof(TypeInfoObject), .tp_dealloc = reinterpret_cast(typeInfoDealloc), .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = PyDoc_STR("IcePy.TypeInfo"), + .tp_doc = PyDoc_STR(IcePy_DOC_TypeInfo), .tp_new = reinterpret_cast(typeInfoNew), }; @@ -3388,7 +3389,7 @@ namespace IcePy .tp_basicsize = sizeof(ExceptionInfoObject), .tp_dealloc = reinterpret_cast(exceptionInfoDealloc), .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_doc = PyDoc_STR("IcePy.ExceptionInfo"), + .tp_doc = PyDoc_STR(IcePy_DOC_ExceptionInfo), .tp_new = reinterpret_cast(exceptionInfoNew), }; // clang-format on diff --git a/python/modules/IcePy/msbuild/icepy.vcxproj b/python/modules/IcePy/msbuild/icepy.vcxproj index 117c910dd26..9735c7c5eca 100644 --- a/python/modules/IcePy/msbuild/icepy.vcxproj +++ b/python/modules/IcePy/msbuild/icepy.vcxproj @@ -63,6 +63,7 @@ + diff --git a/python/python/IcePy-stubs/__init__.pyi b/python/python/IcePy-stubs/__init__.pyi index 10367b91d36..a9d3904aeb9 100644 --- a/python/python/IcePy-stubs/__init__.pyi +++ b/python/python/IcePy-stubs/__init__.pyi @@ -1,15 +1,10 @@ # Copyright (c) ZeroC, Inc. -# IcePy contains (unfortunately) a mix of public and internal APIs. -# The public APIs, things that get re-exported through Ice, must be documented; internal APIs do not. -# -# These doc comments must be synchronized with the documentation in the corresponding IcePy C++ files. -# 1. Sphinx uses the doc comments from the IcePy native module directly. -# 2. IcePy stubs (this file) are used by pyright and IDEs for type checking and code completion. -# -# It would be nice if this file could be generated automatically from the C++ files using `stubgen`: -# `stubgen -m IcePy --include-docstrings --include-private -o IcePy-stubs` -# but for now we maintain it manually since the generated stubs are incomplete for use with pyright. +# This stub is the single source of truth for IcePy docstrings: +# python/modules/IcePy/DocStrings.h is generated from it by scripts/generateIcePyDocs.py, +# and CI verifies that the header is current (scripts/generateIcePyDocs.py --check). + +"""The Internet Communications Engine.""" from collections.abc import Awaitable, Callable from typing import Any, Self, Type, TypeVar @@ -715,19 +710,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 diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 00000000000..83b940eb178 --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,18 @@ +# Scripts + +## generateIcePyDocs.py + +Generates `python/modules/IcePy/DocStrings.h`, the docstring constants the IcePy C extension +ships, from `python/python/IcePy-stubs/__init__.pyi` — the single source of truth for IcePy +docstrings. Each stub declaration becomes one string constant: a signature line, a blank line, +and the prose. + +Run it from anywhere to rewrite the header: + +```shell +python3 scripts/generateIcePyDocs.py +``` + +`--check` regenerates the header to a temporary file, diffs it against the committed one, and +exits non-zero with the diff when the committed header is stale. CI runs this mode; after editing +the stub, regenerate the header and commit both files. diff --git a/scripts/checkIcePyStub.py b/scripts/checkIcePyStub.py deleted file mode 100644 index a956f6d759c..00000000000 --- a/scripts/checkIcePyStub.py +++ /dev/null @@ -1,144 +0,0 @@ -#!/usr/bin/env python3 - -# Copyright (c) ZeroC, Inc. - -""" -Check that the IcePy stub agrees with the IcePy module. - -IcePy is a C extension, so its documentation has to exist twice: Sphinx reads the docstrings the -module ships, and pyright and the IDEs read IcePy-stubs/__init__.pyi. Nothing links the two, so they -drift silently. This compares them and reports where they disagree. - -The signature is compared as well as the prose. autodoc cannot introspect a C extension -- it reads -the first line of each docstring -- so that line is a signature the stub also spells out, and it can -drift just as easily. - -Run it from the repository root after building Ice for Python: - - PYTHONPATH=python/python python3 scripts/checkIcePyStub.py -""" - -from __future__ import annotations - -import ast -import copy -import difflib -import sys -from pathlib import Path - -STUB = Path(__file__).parents[1] / "python" / "python" / "IcePy-stubs" / "__init__.pyi" - - -def signatureOf(node: ast.FunctionDef | ast.AsyncFunctionDef) -> str: - """Render a stub def the way the first line of a C docstring spells it.""" - args = copy.deepcopy(node.args) - if args.posonlyargs and args.posonlyargs[0].arg in ("self", "cls"): - del args.posonlyargs[0] - elif args.args and args.args[0].arg in ("self", "cls"): - del args.args[0] - rendered = f"{node.name}({ast.unparse(args)})" - return f"{rendered} -> {ast.unparse(node.returns)}" if node.returns else rendered - - -def stubEntries() -> dict[str, tuple[str | None, str | None]]: - """Map each name in the stub to its (docstring, signature). Classes have no signature.""" - entries: dict[str, tuple[str | None, str | None]] = {} - for node in ast.parse(STUB.read_text(encoding="utf-8")).body: - if isinstance(node, ast.ClassDef): - entries[node.name] = (ast.get_docstring(node), None) - for member in node.body: - if isinstance(member, (ast.FunctionDef, ast.AsyncFunctionDef)): - entries[f"{node.name}.{member.name}"] = (ast.get_docstring(member), signatureOf(member)) - elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)): - entries[node.name] = (ast.get_docstring(node), signatureOf(node)) - return entries - - -def shipped(name: str) -> tuple[bool, str | None]: - """Return whether IcePy defines name, and the docstring it ships for it.""" - import IcePy - - obj: object = IcePy - for part in name.split("."): - if not hasattr(obj, part): - return False, None - obj = getattr(obj, part) - return True, getattr(obj, "__doc__", None) - - -def split(doc: str | None, name: str) -> tuple[str | None, str]: - """ - Separate a shipped docstring into its signature line and its prose. - - The line only counts as a signature if it opens with the name being documented. Python supplies - its own docstring for an undocumented dunder -- "Return hash(self)." -- which otherwise looks - close enough to one to be mistaken for it. - """ - if not doc: - return None, "" - lines = doc.split("\n") - if lines and lines[0].startswith(f"{name.split('.')[-1]}("): - return lines[0].strip(), "\n".join(lines[1:]).strip() - return None, doc.strip() - - -def isDunder(name: str) -> bool: - """Python writes its own docstring for a dunder it generates, so those carry no signature.""" - leaf = name.rsplit(".", maxsplit=1)[-1] - return leaf.startswith("__") and leaf.endswith("__") - - -def normalize(signature: str) -> str: - """Ignore spacing around default values: the stub is formatted by ast, the docstring by hand.""" - return signature.replace(" = ", "=") - - -def main() -> int: - problems: list[str] = [] - for name, (stubDoc, stubSignature) in sorted(stubEntries().items()): - defined, shippedDoc = shipped(name) - if not defined: - # A private helper the stub declares for pyright need not be an attribute of the module, - # but a public one going missing is the drift this is looking for. - if not name.rsplit(".", maxsplit=1)[-1].startswith("_"): - problems.append(f"{name}: declared in the stub, but IcePy does not define it") - continue - - signature, prose = split(shippedDoc, name) - - if stubDoc and not prose: - problems.append(f"{name}: documented in the stub, but IcePy ships no description") - elif stubDoc and prose and stubDoc.strip() != prose: - diff = "\n".join( - f" {line}" - for line in difflib.unified_diff( - stubDoc.strip().splitlines(), prose.splitlines(), "stub", "IcePy", lineterm="" - ) - ) - problems.append(f"{name}: descriptions differ\n{diff}") - - if stubSignature and not signature and not isDunder(name): - problems.append( - f"{name}: the stub gives a signature, but IcePy's docstring opens with no matching one." - "\n Sphinx reads the signature from that line, so it has to be there." - ) - elif stubSignature and signature and normalize(stubSignature) != normalize(signature): - problems.append(f"{name}: signatures differ\n stub: {stubSignature}\n IcePy: {signature}") - - if problems: - print(f"{len(problems)} difference(s) between the IcePy stub and the IcePy module:\n", file=sys.stderr) - for p in problems: - print(f" {p}", file=sys.stderr) - print( - "\nBoth are hand-written and have to say the same thing: Sphinx reads the module's" - "\ndocstrings, pyright and the IDEs read the stub.", - file=sys.stderr, - ) - return 1 - - print("the IcePy stub matches the IcePy module") - return 0 - - -if __name__ == "__main__": - sys.exit(main()) diff --git a/scripts/generateIcePyDocs.py b/scripts/generateIcePyDocs.py new file mode 100644 index 00000000000..74b2e83bf3e --- /dev/null +++ b/scripts/generateIcePyDocs.py @@ -0,0 +1,222 @@ +#!/usr/bin/env python3 + +# Copyright (c) ZeroC, Inc. + +""" +Generate the IcePy docstring header from the IcePy stub. + +The stub, python/python/IcePy-stubs/__init__.pyi, is the single source of truth for IcePy +docstrings. This script renders each stub declaration as the docstring the C extension ships -- +a signature line, a blank line, and the prose, following the conventions the module already uses -- +and writes them as string constants to python/modules/IcePy/DocStrings.h for the C++ sources to +reference. + +Run it from anywhere; paths are resolved relative to this file: + + python3 scripts/generateIcePyDocs.py # rewrite the header + python3 scripts/generateIcePyDocs.py --check # exit 1 with a diff if the header is stale +""" + +import ast +import difflib +import inspect +import sys +import tempfile +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +STUB = ROOT / "python" / "python" / "IcePy-stubs" / "__init__.pyi" +HEADER = ROOT / "python" / "modules" / "IcePy" / "DocStrings.h" + +# Classes whose tp_doc is the constructor signature line: a C type documents __init__ on the class, +# spelled with the class's name and the positional-only marker, because that is how it is called. +CTOR_CLASSES = {"Communicator", "ObjectPrx", "Operation", "Properties"} + + +def renderParams(fn: ast.FunctionDef, dropSelf: bool) -> str: + """Render a def's parameter list, keeping the positional-only ``/`` marker where the stub + declares one: Sphinx renders the line verbatim, so the marker is part of the signature.""" + args = fn.args + posonly = list(args.posonlyargs) + regular = list(args.args) + if dropSelf: + if posonly and posonly[0].arg == "self": + posonly = posonly[1:] + elif regular and regular[0].arg == "self": + regular = regular[1:] + params = posonly + regular + defaults = [None] * (len(params) - len(args.defaults)) + list(args.defaults) + parts = [] + for param, default in zip(params, defaults): + part = param.arg + if param.annotation is not None: + part += ": " + ast.unparse(param.annotation) + if default is not None: + part += (" = " if param.annotation is not None else "=") + ast.unparse(default) + parts.append(part) + if posonly: + parts.insert(len(posonly), "/") + return ", ".join(parts) + + +def signatureLine(fn: ast.FunctionDef, name: str, dropSelf: bool) -> str: + """Render a def as the signature line of its docstring. A def with no return annotation gets + no ``->`` suffix.""" + line = f"{name}({renderParams(fn, dropSelf)})" + if fn.returns is not None: + line += " -> " + ast.unparse(fn.returns) + return line + + +def isStatic(fn: ast.FunctionDef) -> bool: + return any(isinstance(d, ast.Name) and d.id == "staticmethod" for d in fn.decorator_list) + + +def functionDoc(fns: list[ast.FunctionDef], dropSelf: bool) -> str: + """Render a def -- or an @overload set, which stacks one signature line per overload and takes + its prose from the last def -- as a complete docstring.""" + sigs = "\n".join(signatureLine(fn, fns[0].name, dropSelf) for fn in fns) + doc = ast.get_docstring(fns[-1], clean=True) + return sigs + "\n\n" + doc if doc else sigs + + +def groupDefs(body: list[ast.stmt]) -> dict[str, list[ast.FunctionDef]]: + """Group defs by name, preserving first-occurrence order, so an @overload set renders once.""" + groups: dict[str, list[ast.FunctionDef]] = {} + for node in body: + if isinstance(node, ast.FunctionDef): + groups.setdefault(node.name, []).append(node) + return groups + + +def attributeDocs(body: list[ast.stmt]) -> dict[str, str]: + """An annotated attribute followed by a string literal: the getset doc is that string, + unwrapped to a single physical line (the stub wraps it to the line-length limit; the C source + does not).""" + docs = {} + for prev, node in zip(body, body[1:]): + if ( + isinstance(prev, ast.AnnAssign) + and isinstance(prev.target, ast.Name) + and isinstance(node, ast.Expr) + and isinstance(node.value, ast.Constant) + and isinstance(node.value.value, str) + ): + docs[prev.target.id] = " ".join(inspect.cleandoc(node.value.value).split("\n")) + return docs + + +def classDoc(node: ast.ClassDef) -> str: + doc = ast.get_docstring(node, clean=True) + if doc: + return doc + if node.name in CTOR_CLASSES: + init = groupDefs(node.body)["__init__"][0] + return signatureLine(init, node.name, dropSelf=True) + return f"IcePy.{node.name}" + + +def collect(tree: ast.Module) -> list[tuple[str, str, str, str]]: + """Collect every docstring constant as (python name, constant name, kind, text), in stub + source order. Dunders are skipped: those slots carry CPython-supplied docstrings. So are the + typing helpers and the _t_* constants, which have no docstrings to carry.""" + entries = [("IcePy", "IcePy_DOC_module", "moduledoc", ast.get_docstring(tree, clean=True))] + moduleGroups = groupDefs(tree.body) + emittedFunctions = set() + for node in tree.body: + if isinstance(node, ast.FunctionDef) and node.name not in emittedFunctions: + emittedFunctions.add(node.name) + doc = functionDoc(moduleGroups[node.name], dropSelf=False) + entries.append((f"IcePy.{node.name}", f"IcePy_DOC_{node.name}", "modulefunc", doc)) + elif isinstance(node, ast.ClassDef): + entries.append((f"IcePy.{node.name}", f"IcePy_DOC_{node.name}", "tpdoc", classDoc(node))) + groups = groupDefs(node.body) + attrs = attributeDocs(node.body) + emittedMethods = set() + for member in node.body: + if isinstance(member, ast.FunctionDef) and not member.name.startswith("__"): + if member.name not in emittedMethods: + emittedMethods.add(member.name) + fns = groups[member.name] + doc = functionDoc(fns, dropSelf=not isStatic(fns[0])) + entries.append( + (f"IcePy.{node.name}.{member.name}", f"IcePy_DOC_{node.name}_{member.name}", "method", doc) + ) + elif ( + isinstance(member, ast.AnnAssign) + and isinstance(member.target, ast.Name) + and member.target.id in attrs + ): + entries.append( + ( + f"IcePy.{node.name}.{member.target.id}", + f"IcePy_DOC_{node.name}_{member.target.id}", + "getset", + attrs[member.target.id], + ) + ) + constants = [entry[1] for entry in entries] + duplicates = {c for c in constants if constants.count(c) > 1} + if duplicates: + sys.exit(f"error: duplicate constants: {', '.join(sorted(duplicates))}") + return entries + + +def literal(text: str) -> str: + """Render text as a C++ string literal: a plain quoted literal for a single line, a raw string + literal with a non-colliding delimiter for multiple lines.""" + if "\n" not in text: + return '"' + text.replace("\\", "\\\\").replace('"', '\\"') + '"' + delimiter = "doc" + while f'){delimiter}"' in text: + delimiter += "_" + return f'R"{delimiter}({text}){delimiter}"' + + +def render(entries: list[tuple[str, str, str, str]]) -> str: + lines = [ + "// Copyright (c) ZeroC, Inc.", + "", + "// Generated by scripts/generateIcePyDocs.py from python/python/IcePy-stubs/__init__.pyi. Do not edit.", + "", + "#ifndef ICEPY_DOC_STRINGS_H", + "#define ICEPY_DOC_STRINGS_H", + "", + "// clang-format off", + ] + for _, constant, _, text in entries: + lines.append("") + lines.append(f"inline constexpr const char* {constant} = {literal(text)};") + lines += ["", "// clang-format on", "", "#endif", ""] + return "\n".join(lines) + + +def main() -> None: + if len(sys.argv) > 2 or (len(sys.argv) == 2 and sys.argv[1] != "--check"): + sys.exit(f"usage: {sys.argv[0]} [--check]") + + tree = ast.parse(STUB.read_text(encoding="utf-8")) + if ast.get_docstring(tree) is None: + sys.exit(f"error: {STUB} has no module docstring") + content = render(collect(tree)) + + if len(sys.argv) == 2: + committed = HEADER.read_text(encoding="utf-8") if HEADER.exists() else "" + if content == committed: + return + with tempfile.NamedTemporaryFile("w", suffix=".h", delete=False) as generated: + generated.write(content) + diff = difflib.unified_diff( + committed.splitlines(keepends=True), + content.splitlines(keepends=True), + fromfile=str(HEADER.relative_to(ROOT)), + tofile=generated.name, + ) + sys.stdout.writelines(diff) + sys.exit(f"error: {HEADER.relative_to(ROOT)} is stale; run scripts/generateIcePyDocs.py") + + HEADER.write_text(content, encoding="utf-8") + + +if __name__ == "__main__": + main()