Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

bpo-34206: Improve docs and test coverage for pre-init functions #8023

Merged
merged 29 commits into from
Oct 8, 2024
Merged

bpo-34206: Improve docs and test coverage for pre-init functions #8023

merged 29 commits into from
Oct 8, 2024
+199 −78

Conversation

ncoghlan
Copy link
Contributor

@ncoghlan ncoghlan commented Jun 30, 2018 •
edited
Loading

  • move the Py_Main documentation from the very high level API section
    to the initialization and finalization section
  • make it clear that it encapsulates a full Py_Initialize/Finalize
    cycle of its own
  • point out that exactly which settings will be read and applied
    correctly when called after a separate Py_Initialize or
    Py_InitalizeEx call is version dependent
  • be explicit that Py_IsInitialized can be called prior to
    initialization
  • actually test that Py_IsInitialized can be called prior to
    initialization
  • move the docs for the new Py_BytesMain and Py_InitializeFromConfig
    functions to the initialization and finalization section
  • ensure the new configuration and pre-initialization APIs are explicitly
    listed as being safe to call prior to interpreter initialization
  • other minor tweaks to improve the integration between the docs for
    the traditional initialization API and the new struct-based one.

Closes #78387

https://bugs.python.org/issue34206

@ncoghlan
bpo-34008: Py_Main and Py_IsInitialized are preinit functions
6fd7a02 
- move the Py_Main documentation from the very high level API section
  to the initialization and finalization section
- make it clear that it encapsulates a full Py_Initialize/Finalize
  cycle of its own
- point out that exactly which settings will be read and applied
  correctly when called after a separate Py_Initialize or
  Py_InitalizeEx call is version dependent
- be explicit that Py_IsInitialized can be called prior to
  initialization
- actually test that Py_IsInitialized can be called prior to
  initialization
@ncoghlan ncoghlan requested a review from vstinner June 30, 2018 11:49
vstinner
vstinner reviewed Jul 2, 2018
View reviewed changes
Doc/c-api/veryhigh.rst Outdated Show resolved Hide resolved
Programs/_testembed.c Show resolved Hide resolved
@ncoghlan
Replace note with NEWS entry for Py_Main docs move
eb855e1
@ncoghlan
Further pre-initialization test improvements
68e37d1 
- also check Py_IsInitialized while the interpreter is initialized
  and after it is finalized
- flush stdout in the embedding tests that run code so it appears
  in the expected order when running with "-vv"
- make "-vv" on the subinterpreter embedding tests less spammy
@ncoghlan
Copy link
Contributor Author

Just noting that this is stalled pending further discussion on bpo-34008: there actually appears to be a valid use for calling Py_Main after Py_Initialize, which is essentially treating it as a C level equivalent of the runpy module, and passing the arguments as C strings using the argc/argv convention.

@ncoghlan ncoghlan changed the title bpo-34008: Py_Main and Py_IsInitialized are preinit functions bpo-34206: Py_Main and Py_IsInitialized are preinit functions [WIP - do not merge] Jul 24, 2018
@ncoghlan
Copy link
Contributor Author

Since bpo-34008 was resolved by restoring something close to the Python 3.6 behaviour, I filed a new issue (bpo-34206) to cover clarifying the documentation, and have retitled this PR accordingly.

However, it still needs to be fixed to correctly describe the Python 3.6 and 3.7.1+ behaviour before it can be merged.

vstinner
vstinner reviewed Aug 23, 2019
View reviewed changes
Doc/c-api/init.rst Show resolved Hide resolved
Doc/c-api/init.rst Outdated Show resolved Hide resolved
@ncoghlan ncoghlan changed the title bpo-34206: Py_Main and Py_IsInitialized are preinit functions [WIP - do not merge] bpo-34206: Improves docs and test coverage for pre-init functions Aug 25, 2019
@ncoghlan ncoghlan changed the title bpo-34206: Improves docs and test coverage for pre-init functions bpo-34206: Improve docs and test coverage for pre-init functions Aug 25, 2019
@ncoghlan
Copy link
Contributor Author

@vstinner Reviewing my still open assigned bpo issues, I noticed this PR was still open.

I think my rationale for wanting to move the docs around a bit still holds, so I'd like to merge this for 3.10 and 3.9.

@vstinner
Copy link
Member

@vstinner Reviewing my still open assigned bpo issues, I noticed this PR was still open.

Sorry, I don't have the bandwidth to review it.

ncoghlan
ncoghlan commented Sep 27, 2024
View reviewed changes
Doc/c-api/init.rst Outdated Show resolved Hide resolved
ncoghlan
ncoghlan commented Sep 27, 2024
View reviewed changes
Doc/c-api/init.rst Outdated Show resolved Hide resolved
ncoghlan
ncoghlan commented Oct 7, 2024
View reviewed changes
Doc/c-api/init.rst Outdated Show resolved Hide resolved
willingc
willingc approved these changes Oct 7, 2024
View reviewed changes
Copy link
Contributor

@willingc willingc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docs look good to me. Thanks @ncoghlan.

Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst Outdated Show resolved Hide resolved
Misc/NEWS.d/next/Documentation/2018-07-04-20-35-25.bpo-34008.bqecIb.rst Outdated Show resolved Hide resolved
@ncoghlan @willingc
Apply suggestions from code review
aad97ee 
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
@ncoghlan
Copy link
Contributor Author

ncoghlan commented Oct 8, 2024

Thanks for the review @willingc!

@vstinner This is going to be backported to 3.13, so I didn't add the new PEP 741 API to the list yet, but we should add it after this PR lands.

@ncoghlan ncoghlan enabled auto-merge (squash) October 8, 2024 08:13
@ncoghlan ncoghlan added the needs backport to 3.13 bugs and security fixes label Oct 8, 2024
@ncoghlan ncoghlan merged commit 7c4b6a6 into python:main Oct 8, 2024
38 checks passed
@miss-islington-app
Copy link

Thanks @ncoghlan for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

@miss-islington-app
Copy link

Sorry, @ncoghlan, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 7c4b6a68f263320a2dd19cd5ff63b35c964b1fa8 3.13

ncoghlan added a commit to ncoghlan/cpython that referenced this pull request Oct 8, 2024
@ncoghlan @willingc
[3.13] bpo-34206: Improve docs and test coverage for pre-init functio…
f0fd266 
…ns (pythonGH-8023)

- move the Py_Main documentation from the very high level API section
  to the initialization and finalization section
- make it clear that it encapsulates a full Py_Initialize/Finalize
  cycle of its own
- point out that exactly which settings will be read and applied
  correctly when Py_Main is called after a separate runtime
  initialization call is version dependent
- be explicit that Py_IsInitialized can be called prior to
  initialization
- actually test that Py_IsInitialized can be called prior to
  initialization
- flush stdout in the embedding tests that run code so it appears
  in the expected order when running with "-vv"
- make "-vv" on the subinterpreter embedding tests less spammy

---------

(cherry picked from commit 7c4b6a6)

Co-authored-by: Alyssa Coghlan <ncoghlan@gmail.com>
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
@bedevere-app
Copy link

bedevere-app bot commented Oct 8, 2024

GH-125092 is a backport of this pull request to the 3.13 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Oct 8, 2024
ncoghlan added a commit that referenced this pull request Oct 8, 2024
@ncoghlan @willingc
[3.13] bpo-34206: Improve docs and test coverage for pre-init functio…
6439136 
…ns (GH-8023) (#125092)

- move the Py_Main documentation from the very high level API section
  to the initialization and finalization section
- make it clear that it encapsulates a full Py_Initialize/Finalize
  cycle of its own
- point out that exactly which settings will be read and applied
  correctly when Py_Main is called after a separate runtime
  initialization call is version dependent
- be explicit that Py_IsInitialized can be called prior to
  initialization
- actually test that Py_IsInitialized can be called prior to
  initialization
- flush stdout in the embedding tests that run code so it appears
  in the expected order when running with "-vv"
- make "-vv" on the subinterpreter embedding tests less spammy

---------

(cherry picked from commit 7c4b6a6)

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@vstinner vstinner vstinner left review comments

@willingc willingc willingc approved these changes

Assignees

@ncoghlan ncoghlan

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Move and clarify Py_Main documentation
8 participants
@ncoghlan @vstinner @furkanonder @willingc @hugovk @the-knights-who-say-ni @ezio-melotti @bedevere-bot