bpo-36487: Make C-API docs clear about what the main interpreter is #12666

nanjekyejoannah · 2019-04-02T19:21:05Z

I have added documentation to clarify on what the main interpreter is.

https://bugs.python.org/issue36487

nanjekyejoannah · 2019-04-02T19:33:12Z

… into issue36487

ericsnowcurrently

The flow of the text doesn't line up as well with this change. Consider splitting the original paragraph right before the final sentence, like this:

 you to do that.  You can switch between sub-interpreters using the	
+:c:func:`PyThreadState_Swap` function.
+
+<explanation of main interpreter>
+
+You can create and destroy sub-interpreters using the following
+functions:

I've also left a comment for the paragraph about the main interpreter.

ericsnowcurrently · 2019-04-05T17:30:12Z

Doc/c-api/init.rst

+Before sub-interpreters, there is a main interpreter which is the first one
+created by the CPython runtime on startup when the ``python`` command is
+run. The :c:func:`PyInterpreterState_Main` funtion returns a pointer to this
+main interpreter's state.


This description of the main interpreter could be a bit more direct but the focus should remain within the context of subinterpreters. For instance, there's no need here to mention any specific API related to the main interpreter. Anyway, I've updated the BPO issue with a list of key points to cover.

FWIW, I'm not sure whether it would be better to keep the main-related text small (e.g. one short paragraph) or to make it comprehensive (e.g. across multiple paragraphs). If we go with that latter then it may make sense to have a separate section nearby for the main interpreter.

I think it makes sense to keep things minimal for now, and defer more comprehensive documentation to the resolution of the PEP for a Python level subinterpreter API.

@ncoghlan I agree to this being a small paragraph for now most especially given the current structure of the docs. Though I also have to warn you that incorporating all the points @ericsnowcurrently suggests in the BPO will lead to a big paragraph.

bedevere-bot · 2019-04-05T17:40:19Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

nanjekyejoannah · 2019-04-10T16:40:22Z

@ericsnowcurrently , I have made some edits.

Note: I just made a summary of your suggestions here : https://bugs.python.org/issue36487

it would have had much more detail if it was in a separate section though.

PTAL

ericsnowcurrently

That's looking good! Thanks for working on this. I just have a few comments.

Doc/c-api/init.rst

ncoghlan

I finally figured out how the "Suggestions" UI works :)

(There's a hard-to-describe icon when editing your comments that adds the line you're commenting on with the markup to turn it into a suggested change)

Doc/c-api/init.rst

Misc/NEWS.d/next/Documentation/2019-04-02-19-23-00.bpo-36487.Jg6-MG.rst

Doc/c-api/init.rst

Co-Authored-By: Nick Coghlan <ncoghlan@gmail.com>

nanjekyejoannah · 2019-06-24T18:14:58Z

I have made the requested changes; please review again.

bedevere-bot · 2019-06-24T18:15:02Z

Thanks for making the requested changes!

@ericsnowcurrently: please review the changes made to this pull request.

ericsnowcurrently

Thanks for the updates. This is looking good correctness-wise. I've left a few comments with tweaks to clarify a little and to make the paragraph flow a bit more cohesively. If you put them all together, the results looks like this:

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.

Doc/c-api/init.rst

bedevere-bot · 2019-06-25T21:43:37Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

nanjekyejoannah · 2019-07-18T16:27:00Z

I have made the requested changes; please review again.

bedevere-bot · 2019-07-18T16:27:03Z

Thanks for making the requested changes!

@ericsnowcurrently: please review the changes made to this pull request.

ericsnowcurrently

LGTM

Thanks for working on this, @nanjekyejoannah!

miss-islington · 2019-08-02T15:54:57Z

Thanks @nanjekyejoannah for the PR, and @ericsnowcurrently for merging it 🌮🎉.. I'm working now to backport this PR to: 3.8.
🐍🍒⛏🤖

…ythongh-12666) (cherry picked from commit 854d0a4) Co-authored-by: Joannah Nanjekye <33177550+nanjekyejoannah@users.noreply.github.com>

…h-15080) (cherry picked from commit 854d0a4) (gh-12666) Co-authored-by: Joannah Nanjekye <33177550+nanjekyejoannah@users.noreply.github.com>

…ythongh-12666)

Make C-API docs clear about what the main interpreter is

8ed5856

the-knights-who-say-ni added the CLA signed label Apr 2, 2019

bedevere-bot added docs Documentation in the Doc dir awaiting review labels Apr 2, 2019

blurb-it bot and others added 2 commits April 2, 2019 19:23

📜🤖 Added by blurb_it.

0d4eb4d

nit edit

8d86ce1

nanjekyejoannah added 2 commits April 2, 2019 15:34

nit edit

72fb60e

Merge branch 'issue36487' of https://github.com/nanjekyejoannah/cpython…

9416dbf

… into issue36487

ericsnowcurrently requested changes Apr 5, 2019

View reviewed changes

bedevere-bot added awaiting changes and removed awaiting review labels Apr 5, 2019

edits to Make C-API docs clear about what the main interpreter is

30a0ae2

csabella requested a review from ericsnowcurrently May 13, 2019 04:08

ericsnowcurrently requested changes Jun 14, 2019

View reviewed changes

Doc/c-api/init.rst Outdated Show resolved Hide resolved

Doc/c-api/init.rst Outdated Show resolved Hide resolved

Doc/c-api/init.rst Outdated Show resolved Hide resolved

ncoghlan reviewed Jun 15, 2019

View reviewed changes

Doc/c-api/init.rst Outdated Show resolved Hide resolved

Misc/NEWS.d/next/Documentation/2019-04-02-19-23-00.bpo-36487.Jg6-MG.rst Outdated Show resolved Hide resolved

Doc/c-api/init.rst Outdated Show resolved Hide resolved

Doc/c-api/init.rst Outdated Show resolved Hide resolved

nanjekyejoannah and others added 3 commits June 15, 2019 13:14

Update Doc/c-api/init.rst

b5b2716

Co-Authored-By: Nick Coghlan <ncoghlan@gmail.com>

Update Doc/c-api/init.rst

3e26562

Co-Authored-By: Nick Coghlan <ncoghlan@gmail.com>

Fix updates on the C API docs

ba97ef9

bedevere-bot added awaiting change review and removed awaiting changes labels Jun 24, 2019

ericsnowcurrently requested changes Jun 25, 2019

View reviewed changes

bedevere-bot added awaiting changes and removed awaiting change review labels Jun 25, 2019

clarity updates

9c5de37

bedevere-bot added awaiting change review and removed awaiting changes labels Jul 18, 2019

ericsnowcurrently approved these changes Aug 2, 2019

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting change review labels Aug 2, 2019

ericsnowcurrently merged commit 854d0a4 into python:master Aug 2, 2019

bedevere-bot removed the awaiting merge label Aug 2, 2019

ericsnowcurrently added the needs backport to 3.8 label Aug 2, 2019

lisroach pushed a commit to lisroach/cpython that referenced this pull request Sep 10, 2019

bpo-36487: Make C-API docs clear about what the main interpreter is. (p…

6a06d77

…ythongh-12666)

DinoV pushed a commit to DinoV/cpython that referenced this pull request Jan 14, 2020

bpo-36487: Make C-API docs clear about what the main interpreter is. (p…

02a52c7

…ythongh-12666)

websurfer5 pushed a commit to websurfer5/cpython that referenced this pull request Jul 20, 2020

bpo-36487: Make C-API docs clear about what the main interpreter is. (p…

01e9428

…ythongh-12666)

Uh oh!

bpo-36487: Make C-API docs clear about what the main interpreter is #12666

bpo-36487: Make C-API docs clear about what the main interpreter is #12666

Uh oh!

Conversation

nanjekyejoannah commented Apr 2, 2019 • edited by bedevere-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nanjekyejoannah commented Apr 2, 2019

Uh oh!

ericsnowcurrently left a comment

Choose a reason for hiding this comment

Uh oh!

ericsnowcurrently Apr 5, 2019

Choose a reason for hiding this comment

Uh oh!

ncoghlan Apr 7, 2019

Choose a reason for hiding this comment

Uh oh!

nanjekyejoannah Apr 9, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bedevere-bot commented Apr 5, 2019

Uh oh!

nanjekyejoannah commented Apr 10, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ericsnowcurrently left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ncoghlan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nanjekyejoannah commented Jun 24, 2019

Uh oh!

bedevere-bot commented Jun 24, 2019

Uh oh!

ericsnowcurrently left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bedevere-bot commented Jun 25, 2019

Uh oh!

nanjekyejoannah commented Jul 18, 2019

Uh oh!

bedevere-bot commented Jul 18, 2019

Uh oh!

ericsnowcurrently left a comment

Choose a reason for hiding this comment

Uh oh!

miss-islington commented Aug 2, 2019

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

nanjekyejoannah commented Apr 2, 2019 •

edited by bedevere-bot

Loading

nanjekyejoannah Apr 9, 2019 •

edited

Loading

nanjekyejoannah commented Apr 10, 2019 •

edited

Loading