Skip to content

Py_Main and Py_RunMain SystemExit documentation does not match actual behavior #133264

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
Closed
mhsmith opened this issue May 1, 2025 · 10 comments
Closed

Py_Main and Py_RunMain SystemExit documentation does not match actual behavior #133264

mhsmith opened this issue May 1, 2025 · 10 comments
Labels
docs Documentation in the Doc dir topic-C-API

Comments

@mhsmith
Copy link
Member

mhsmith commented May 1, 2025 •
edited by bedevere-app bot
Loading

A few months ago, #8023 added some details to the docs about how Py_RunMain determines its exit status. Specifically, it wrote thatPy_RunMain exits the process on an unhandled SystemExit.

But this isn't the case, at least not when running via the pymain_run_module path (the other paths aren't so clear to me). The relevant code is in pymain_err_print, which specifically checks for SystemExit in order to avoid passing it to PyErr_Print, which is where exit would actually be called.

My understanding is that Py_RunMain was intended for an embedded context, in which case exiting the process is probably not desirable.

The docs of Py_Main have specified the process exiting behavior for much longer, but right now it looks like both functions share the same implementation.

@vstinner @ncoghlan

Linked PRs
@mhsmith mhsmith added the docs Documentation in the Doc dir label May 1, 2025
@mhsmith mhsmith changed the title Py_RunMain SystemExit documentation does not match actual behavior Py_Main and Py_RunMain SystemExit documentation does not match actual behavior May 1, 2025
@vstinner
Copy link
Member

vstinner commented May 2, 2025

Do you want to propose a PR to update the documentation?

@mhsmith
Copy link
Member Author

mhsmith commented Jun 8, 2025

I considered it, but it's not clear to me whether the documentation or the implementation is wrong.

@vstinner
Copy link
Member

vstinner commented Jun 9, 2025

You're correct that Py_RunMain() is designed to embed Python in an application. Calling exit(code) would be bad in this case. Py_RunMain() return value is an exit code. SystemExit(code) becomes an exit code, it doesn't call exit(code).

@mhsmith
Copy link
Member Author

mhsmith commented Jun 9, 2025

But what about Py_Main? Its documentation has stated for many years that an unhandled SystemExit will exit the process, but the implementation no longer does that.

@vstinner
Copy link
Member

vstinner commented Jun 9, 2025

Py_Main() calls Py_RunMain().

@mhsmith
Copy link
Member Author

mhsmith commented Jun 9, 2025

Yes, that's my point. Neither function currently exits the process on an unhandled SystemExit, but in the case of Py_Main I suspect this behavior has changed unintentionally at some point in the past.

@vstinner
Copy link
Member

vstinner commented Jun 9, 2025

Correct, the behavior changed. The documentation should be updated.

@vstinner
Copy link
Member

vstinner commented Jun 9, 2025

this behavior has changed unintentionally at some point in the past.

Correction: these changes were made on purpose.

@mhsmith
Copy link
Member Author

mhsmith commented Jun 10, 2025

OK, it looks like this was done in #13390 in 2019, so anyone who was affected by the change has already adapted to it. So I'll make a PR to update the documentation.

@bedevere-app bedevere-app bot mentioned this issue Jun 10, 2025
Merged
vstinner pushed a commit that referenced this issue Jun 11, 2025
@mhsmith
gh-133264: Correct documentation of how Py_Main and Py_RunMain handle…
b706ff0 
… SystemExit (#135337)
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Jun 11, 2025
@mhsmith @miss-islington
pythongh-133264: Correct documentation of how Py_Main and Py_RunMain …
a5788f7 
…handle SystemExit (pythonGH-135337)

(cherry picked from commit b706ff0)

Co-authored-by: Malcolm Smith <smith@chaquo.com>
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Jun 11, 2025
@mhsmith @miss-islington
pythongh-133264: Correct documentation of how Py_Main and Py_RunMain …
1b98f7e 
…handle SystemExit (pythonGH-135337)

(cherry picked from commit b706ff0)

Co-authored-by: Malcolm Smith <smith@chaquo.com>
This was referenced Jun 11, 2025
Merged
Merged
vstinner pushed a commit that referenced this issue Jun 11, 2025
@miss-islington @mhsmith
[3.14] gh-133264: Correct documentation of how Py_Main and Py_RunMain…
98136dd 
… handle SystemExit (GH-135337) (#135394)

gh-133264: Correct documentation of how Py_Main and Py_RunMain handle SystemExit (GH-135337)
(cherry picked from commit b706ff0)

Co-authored-by: Malcolm Smith <smith@chaquo.com>
vstinner pushed a commit that referenced this issue Jun 11, 2025
@miss-islington @mhsmith
[3.13] gh-133264: Correct documentation of how Py_Main and Py_RunMain…
d24d925 
… handle SystemExit (GH-135337) (#135395)

gh-133264: Correct documentation of how Py_Main and Py_RunMain handle SystemExit (GH-135337)
(cherry picked from commit b706ff0)

Co-authored-by: Malcolm Smith <smith@chaquo.com>
@ncoghlan
Copy link
Contributor

As far as why #8023 didn't get this right: I forgot the behaviour had changed, and added the outdated info from the Py_Main docs to the Py_RunMain docs when expanding the latter (without checking it was still true).

Thanks for picking up and resolving the oversight!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs Documentation in the Doc dir topic-C-API
Projects
docs issues
Status: Todo
Milestone
No milestone
Development

No branches or pull requests
4 participants
@mhsmith @vstinner @ncoghlan @picnixz