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

[nanjekyejoannah]

BPO	36487
Nosy	@ncoghlan, @ericsnowcurrently, @nanjekyejoannah
PRs	bpo-36487: Make C-API docs clear about what the main interpreter is #12666 [3.8] bpo-36487: Make C-API docs clear about what the main interpreter is. (gh-12666) #15080

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/nanjekyejoannah'
closed_at = <Date 2019-08-02.15:54:28.914>
created_at = <Date 2019-03-30.15:55:50.543>
labels = ['3.8', '3.9', 'docs']
title = 'Make C-API docs  clear about what the "main" interpreter is'
updated_at = <Date 2019-08-02.17:49:41.492>
user = 'https://github.com/nanjekyejoannah'

bugs.python.org fields:

activity = <Date 2019-08-02.17:49:41.492>
actor = 'eric.snow'
assignee = 'nanjekyejoannah'
closed = True
closed_date = <Date 2019-08-02.15:54:28.914>
closer = 'eric.snow'
components = ['Documentation']
creation = <Date 2019-03-30.15:55:50.543>
creator = 'nanjekyejoannah'
dependencies = []
files = []
hgrepos = []
issue_num = 36487
keywords = ['patch']
message_count = 6.0
messages = ['339207', '339508', '339509', '348904', '348906', '348909']
nosy_count = 3.0
nosy_names = ['ncoghlan', 'eric.snow', 'nanjekyejoannah']
pr_nums = ['12666', '15080']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue36487'
versions = ['Python 3.8', 'Python 3.9']

[nanjekyejoannah]

Following up a discussion on a PR here : #12238, There is need to make sure the C-API docs are clear about what the "main" interpreter is.

[ericsnowcurrently]

I should have added something like this earlier, but here are key points to consider covering:

• "main" interpreter is the original, created when the runtime initializes
• historically almost always the only Python interpreter in a process
  • this is changing (more projects using subinterpreters, PEP-554)
  • in the "python" executable, subinterpreters available via extension modules (but uncommon)
• it has extra responsiblities:
  • signal handling, in main thread
  • "pending calls", in main thread
    • not necessarily something to publicize :)
  • running in the "main" thread
    • can be taken over by a sub-interpreter, but not likely
  • execution *during* runtime initialization
  • usually (always?) the active interpreter during runtime finalization
  • others?
• no strong link between interpreters (e.g. main <--> sub <--> sub)
  • no record of what interpreter was active (if any) when a subinterpreter was created
  • no "parent" interpreter
  • thread states may share thread ID
• a bunch of stuff in the C-API and in the runtime still assumes that the main interpreter is running in the current OS thread
• other stuff?

Not all of that necessarily belongs there in the docs, but a lot of it does. :)

[nanjekyejoannah]

Thanks for this feedback. Let me see how I can incorporate this in the PR.

[ericsnowcurrently]

New changeset 854d0a4 by Eric Snow (Joannah Nanjekye) in branch 'master':
bpo-36487: Make C-API docs clear about what the main interpreter is. (gh-12666)
854d0a4

[ericsnowcurrently]

Thanks, Joannah!

[ericsnowcurrently]

New changeset 375f35b by Eric Snow (Miss Islington (bot)) in branch '3.8':
bpo-36487: Make C-API docs clear about what the main interpreter is. (gh-15080)
375f35b