[Python-checkins] bpo-36487: Make C-API docs clear about what the main interpreter is. (gh-15080)

[Eric Snow]

https://github.com/python/cpython/commit/375f35be0688da0fc0f27afc4faea76590d7c24d
commit: 375f35be0688da0fc0f27afc4faea76590d7c24d
branch: 3.8
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: Eric Snow <ericsnowcurrently at gmail.com>
date: 2019-08-02T11:49:38-06:00
summary:

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

(cherry picked from commit 854d0a4b98b13629252e21edaf2b785b429e5135) (gh-12666)

Co-authored-by: Joannah Nanjekye <33177550+nanjekyejoannah at users.noreply.github.com>

files:
A Misc/NEWS.d/next/Documentation/2019-04-02-19-23-00.bpo-36487.Jg6-MG.rst
M Doc/c-api/init.rst

diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index a0ac4d21d139..4985a1d867e2 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 000000000000..c8eb05b6c79c
--- /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