From 46cc29639ef466a2f0ae8cdc33a2c2145f36c970 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Fri, 13 Sep 2019 14:20:04 +0100 Subject: [PATCH 1/4] Clarify documentation of PyState_AddModule This was never intented to be called manually from PyInit_*. Also, clarify PyState_RemoveModule return value. --- Doc/c-api/module.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst index feca1ec2a057ad..00d69c43365d3d 100644 --- a/Doc/c-api/module.rst +++ b/Doc/c-api/module.rst @@ -485,10 +485,17 @@ since multiple such modules can be created from a single definition. Only effective on modules created using single-phase initialization. + The function is intended for implementing alternative import mechanisms. + Python calls PyState_AddModule automatically when importing a module; it + is generally not necessary to call it at module initialization time. + + Return 0 on success or -1 on failure. + .. versionadded:: 3.3 .. c:function:: int PyState_RemoveModule(PyModuleDef *def) Removes the module object created from *def* from the interpreter state. + Return 0 on success or -1 on failure. .. versionadded:: 3.3 From 96a53b214c384f0af37a9b6fd526835a2a7b24bc Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Tue, 24 Sep 2019 16:33:45 +0200 Subject: [PATCH 2/4] Point out that Python only calls PyState_AddModule after a module is imported. --- Doc/c-api/module.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst index 00d69c43365d3d..efb52efb94763f 100644 --- a/Doc/c-api/module.rst +++ b/Doc/c-api/module.rst @@ -485,9 +485,11 @@ since multiple such modules can be created from a single definition. Only effective on modules created using single-phase initialization. - The function is intended for implementing alternative import mechanisms. - Python calls PyState_AddModule automatically when importing a module; it - is generally not necessary to call it at module initialization time. + Python calls ``PyState_AddModule`` automatically after importing a module, + so it is unnecessary (but harmless) to call it from module initialization + code, unless that code itself needs the module to be registered. + The function is mainly intended for implementing alternative import + mechanisms. Return 0 on success or -1 on failure. From 8dddb47db450188e1e89204faeb47e51bd71a1ad Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Tue, 22 Oct 2019 13:04:41 +0200 Subject: [PATCH 3/4] Apply Nick's suggestions Co-Authored-By: Nick Coghlan --- Doc/c-api/module.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst index efb52efb94763f..14030d9649cef4 100644 --- a/Doc/c-api/module.rst +++ b/Doc/c-api/module.rst @@ -487,9 +487,9 @@ since multiple such modules can be created from a single definition. Python calls ``PyState_AddModule`` automatically after importing a module, so it is unnecessary (but harmless) to call it from module initialization - code, unless that code itself needs the module to be registered. + code. An explicit call is needed only if the module's own init code subsequently calls ``PyState_FindModule``. The function is mainly intended for implementing alternative import - mechanisms. + mechanisms (either by calling it directly, or by referring to its implementation for details of the required state updates). Return 0 on success or -1 on failure. From 904535b45b29fad953bb287d61f1e65358d836da Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Tue, 22 Oct 2019 13:06:36 +0200 Subject: [PATCH 4/4] Wrap lines --- Doc/c-api/module.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst index 14030d9649cef4..53057e22dd719b 100644 --- a/Doc/c-api/module.rst +++ b/Doc/c-api/module.rst @@ -487,9 +487,11 @@ since multiple such modules can be created from a single definition. Python calls ``PyState_AddModule`` automatically after importing a module, so it is unnecessary (but harmless) to call it from module initialization - code. An explicit call is needed only if the module's own init code subsequently calls ``PyState_FindModule``. + code. An explicit call is needed only if the module's own init code + subsequently calls ``PyState_FindModule``. The function is mainly intended for implementing alternative import - mechanisms (either by calling it directly, or by referring to its implementation for details of the required state updates). + mechanisms (either by calling it directly, or by referring to its + implementation for details of the required state updates). Return 0 on success or -1 on failure.