From 3341106278b0c437079e3738a67825b35cc31f8c Mon Sep 17 00:00:00 2001 From: Anthony Shaw Date: Thu, 30 Nov 2023 14:25:30 +1100 Subject: [PATCH 1/5] Document interpreter ID public API methods --- Doc/c-api/interpreter.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 Doc/c-api/interpreter.rst diff --git a/Doc/c-api/interpreter.rst b/Doc/c-api/interpreter.rst new file mode 100644 index 00000000000000..e0c769b7183915 --- /dev/null +++ b/Doc/c-api/interpreter.rst @@ -0,0 +1,26 @@ +.. highlight:: c + +.. _interpreters: + +Interpreters +============ + +Interpreter ID API +------------------ + +.. c:var:: PyTypeObject PyInterpreterID_Type + + This instance of :c:type:`PyTypeObject` represents the Python interpreter ID type. + +.. c:function:: PyObject* PyInterpreterID_New(int64_t id) + + Returns a new interpreter ID object with the given *id*. + +.. c:function:: PyInterpreterState* PyInterpreterID_LookUp(PyObject *requested_id) + + Returns a :term:`borrowed reference` to the :c:type:`PyInterpreterState` interpreter state for the given interpreter ID object *requested_id*. + Fails with :c:data:`PyExc_RuntimeError` if the interpreter is not found. + +.. c:function:: PyObject* PyInterpreterState_GetIDObject(PyInterpreterState *interp) + + Returns a new interpreter ID object for the given interpreter state *interp*. From ebd3bcba41f0b52298d6312ddaf085a6a920ea8b Mon Sep 17 00:00:00 2001 From: Anthony Shaw Date: Thu, 30 Nov 2023 14:49:40 +1100 Subject: [PATCH 2/5] Add documentation for interpreter ID objects --- Doc/c-api/concrete.rst | 1 + Doc/c-api/interpreter.rst | 8 ++++++-- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst index 880f7b15ce68e8..daf4681a58801a 100644 --- a/Doc/c-api/concrete.rst +++ b/Doc/c-api/concrete.rst @@ -117,3 +117,4 @@ Other Objects contextvars.rst datetime.rst typehints.rst + interpreter.rst diff --git a/Doc/c-api/interpreter.rst b/Doc/c-api/interpreter.rst index e0c769b7183915..5ae88fc3f32499 100644 --- a/Doc/c-api/interpreter.rst +++ b/Doc/c-api/interpreter.rst @@ -5,8 +5,12 @@ Interpreters ============ -Interpreter ID API ------------------- +Interpreter ID Objects +---------------------- + +A interpreter ID identifies a interpreter and may be used as an int. + +.. versionadded:: 3.12 .. c:var:: PyTypeObject PyInterpreterID_Type From 0bdabbf63e88d9b6f92421380dafb17a19330872 Mon Sep 17 00:00:00 2001 From: Anthony Shaw Date: Thu, 30 Nov 2023 15:01:58 +1100 Subject: [PATCH 3/5] Move the docs to the init file --- Doc/c-api/concrete.rst | 1 - Doc/c-api/init.rst | 23 +++++++++++++++++++++++ Doc/c-api/interpreter.rst | 30 ------------------------------ 3 files changed, 23 insertions(+), 31 deletions(-) delete mode 100644 Doc/c-api/interpreter.rst diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst index daf4681a58801a..880f7b15ce68e8 100644 --- a/Doc/c-api/concrete.rst +++ b/Doc/c-api/concrete.rst @@ -117,4 +117,3 @@ Other Objects contextvars.rst datetime.rst typehints.rst - interpreter.rst diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index e89641f74c7491..c60bdca3336bcd 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1464,6 +1464,29 @@ function. You can create and destroy them using the following functions: :c:func:`Py_FinalizeEx` will destroy all sub-interpreters that haven't been explicitly destroyed at that point. +Interpreter ID Objects +---------------------- + +A interpreter ID identifies a interpreter and may be used as an int. + +.. versionadded:: 3.12 + +.. c:var:: PyTypeObject PyInterpreterID_Type + + This instance of :c:type:`PyTypeObject` represents the Python interpreter ID type. + +.. c:function:: PyObject* PyInterpreterID_New(int64_t id) + + Returns a new interpreter ID object with the given *id*. + +.. c:function:: PyInterpreterState* PyInterpreterID_LookUp(PyObject *requested_id) + + Returns a :term:`borrowed reference` to the :c:type:`PyInterpreterState` interpreter state for the given interpreter ID object *requested_id*. + Fails with :c:data:`PyExc_RuntimeError` if the interpreter is not found. + +.. c:function:: PyObject* PyInterpreterState_GetIDObject(PyInterpreterState *interp) + + Returns a new interpreter ID object for the given interpreter state *interp*. A Per-Interpreter GIL --------------------- diff --git a/Doc/c-api/interpreter.rst b/Doc/c-api/interpreter.rst deleted file mode 100644 index 5ae88fc3f32499..00000000000000 --- a/Doc/c-api/interpreter.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. highlight:: c - -.. _interpreters: - -Interpreters -============ - -Interpreter ID Objects ----------------------- - -A interpreter ID identifies a interpreter and may be used as an int. - -.. versionadded:: 3.12 - -.. c:var:: PyTypeObject PyInterpreterID_Type - - This instance of :c:type:`PyTypeObject` represents the Python interpreter ID type. - -.. c:function:: PyObject* PyInterpreterID_New(int64_t id) - - Returns a new interpreter ID object with the given *id*. - -.. c:function:: PyInterpreterState* PyInterpreterID_LookUp(PyObject *requested_id) - - Returns a :term:`borrowed reference` to the :c:type:`PyInterpreterState` interpreter state for the given interpreter ID object *requested_id*. - Fails with :c:data:`PyExc_RuntimeError` if the interpreter is not found. - -.. c:function:: PyObject* PyInterpreterState_GetIDObject(PyInterpreterState *interp) - - Returns a new interpreter ID object for the given interpreter state *interp*. From b9a8be3a04139eff808d4c6c247b71721ba627f5 Mon Sep 17 00:00:00 2001 From: Anthony Shaw Date: Thu, 30 Nov 2023 15:19:47 +1100 Subject: [PATCH 4/5] Add PyUnstable_InterpreterState_GetMainModule --- Doc/c-api/init.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index c60bdca3336bcd..140ea7af0c624b 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1225,6 +1225,12 @@ All of the following functions must be called after :c:func:`Py_Initialize`. :c:func:`PyEval_SaveThread` is a higher-level function which is always available (even when threads have not been initialized). +.. c:function:: PyObject* PyUnstable_InterpreterState_GetMainModule(PyInterpreterState *interp) + + Returns a :term:`strong reference` to the ``__main__`` module of the given interpreter *interp*. + Fails with a :exc:`RuntimeError` if the interpreter is not initialized. + + .. versionadded:: 3.12 .. _sub-interpreter-support: @@ -1482,7 +1488,7 @@ A interpreter ID identifies a interpreter and may be used as an int. .. c:function:: PyInterpreterState* PyInterpreterID_LookUp(PyObject *requested_id) Returns a :term:`borrowed reference` to the :c:type:`PyInterpreterState` interpreter state for the given interpreter ID object *requested_id*. - Fails with :c:data:`PyExc_RuntimeError` if the interpreter is not found. + Fails with :exc:`RuntimeError` if the interpreter is not found. .. c:function:: PyObject* PyInterpreterState_GetIDObject(PyInterpreterState *interp) From 8f9d7e14dd1aacfdb7450d27b1107356c4e3dc16 Mon Sep 17 00:00:00 2001 From: Anthony Shaw Date: Thu, 30 Nov 2023 18:45:05 +1100 Subject: [PATCH 5/5] Add blurb --- .../2023-11-30-18-44-35.gh-issue-107784.5okblM.rst | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2023-11-30-18-44-35.gh-issue-107784.5okblM.rst diff --git a/Misc/NEWS.d/next/Documentation/2023-11-30-18-44-35.gh-issue-107784.5okblM.rst b/Misc/NEWS.d/next/Documentation/2023-11-30-18-44-35.gh-issue-107784.5okblM.rst new file mode 100644 index 00000000000000..3cfaddfceb8c22 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2023-11-30-18-44-35.gh-issue-107784.5okblM.rst @@ -0,0 +1,2 @@ +Added documentation for the ``PyUnstable_InterpreterState_GetMainModule`` +and ``PyInterpreterID`` C-API. Patch by Anthony Shaw.