gh-121874: Define audit-event open parameters consistently

[bmwiedemann]

Define audit-event open parameters consistently to be the same as in

Doc/library/io.rst:   .. audit-event:: open path,mode,flags io.open
Doc/library/os.rst:   .. audit-event:: open path,mode,flags os.open

to avoid triggering a race-condition in Sphinx
that causes non-deterministic output.

See https://reproducible-builds.org/ for why this matters.

Fixes: #121874

This patch was done while working on reproducible builds for openSUSE, sponsored by the NLnet NGI0 fund.

• Issue: docs: inconsistent open and io.open audit-event parameters #121874

---

📚 Documentation preview 📚: https://cpython-previews--121883.org.readthedocs.build/

[hugovk]

io.open is an alias for open and both have a file parameter rather than name.

https://docs.python.org/3/library/functions.html#open says:

open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

...

Raises an auditing event open with arguments file, mode, flags.

https://docs.python.org/3/library/io.html#io.open says:

io.open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

...

This function raises an auditing event open with arguments path, mode and flags. The mode and flags arguments may have been modified or inferred from the original call.

Should we change both to file rather than path? And write them all in italics?

[bmwiedemann]

I tried that and found that os.open also needs to be adapted then, making the whole change more intrusive: https://github.com/bmwiedemann/cpython/pull/new/docrace2

[serhiy-storchaka]

This is incorrect. The name of the parameter is file, not path.

[bedevere-app]

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.

[bmwiedemann]

I have made the requested changes; please review again.

[bedevere-app]

Thanks for making the requested changes!

@serhiy-storchaka: please review the changes made to this pull request.

[serhiy-storchaka]

LGTM.

[miss-islington-app]

Thanks @bmwiedemann for the PR, and @serhiy-storchaka for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

[miss-islington-app]

Thanks @bmwiedemann for the PR, and @serhiy-storchaka for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

[bedevere-app]

GH-121955 is a backport of this pull request to the 3.12 branch.

[bedevere-app]

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