From: Joannah Nanjekye <33177550+nanjekyejoannah@users.noreply.github.com>
Date: Fri, 2 Aug 2019 15:50:22 +0000 (-0300)
Subject: bpo-36487: Make C-API docs  clear about what the main interpreter is. (gh-12666)
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=854d0a4b98b13629252e21edaf2b785b429e5135;p=python

bpo-36487: Make C-API docs  clear about what the main interpreter is. (gh-12666)
---

diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index a0ac4d21d1..4985a1d867 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -1141,10 +1141,18 @@ Sub-interpreter support
 
 While in most uses, you will only embed a single Python interpreter, there
 are cases where you need to create several independent interpreters in the
-same process and perhaps even in the same thread.  Sub-interpreters allow
-you to do that.  You can switch between sub-interpreters using the
-:c:func:`PyThreadState_Swap` function.  You can create and destroy them
-using the following functions:
+same process and perhaps even in the same thread. Sub-interpreters allow
+you to do that.
+
+The "main" interpreter is the first one created when the runtime initializes.
+It is usually the only Python interpreter in a process.  Unlike sub-interpreters,
+the main interpreter has unique process-global responsibilities like signal
+handling.  It is also responsible for execution during runtime initialization and
+is usually the active interpreter during runtime finalization.  The
+:c:func:`PyInterpreterState_Main` funtion returns a pointer to its state.
+
+You can switch between sub-interpreters using the :c:func:`PyThreadState_Swap`
+function. You can create and destroy them using the following functions:
 
 
 .. c:function:: PyThreadState* Py_NewInterpreter()
diff --git a/Misc/NEWS.d/next/Documentation/2019-04-02-19-23-00.bpo-36487.Jg6-MG.rst b/Misc/NEWS.d/next/Documentation/2019-04-02-19-23-00.bpo-36487.Jg6-MG.rst
new file mode 100755
index 0000000000..c8eb05b6c7
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2019-04-02-19-23-00.bpo-36487.Jg6-MG.rst
@@ -0,0 +1 @@
+Make C-API docs clear about what the "main" interpreter is.
\ No newline at end of file