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

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

Closed
bmwiedemann opened this issue Jul 16, 2024 · 3 comments · Fixed by #121883
Closed

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

bmwiedemann opened this issue Jul 16, 2024 · 3 comments · Fixed by #121883
Labels
docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error

Comments

@bmwiedemann
Copy link
Contributor

bmwiedemann commented Jul 16, 2024 •
edited by bedevere-app bot
Loading

Bug report

Bug description:

While working on reproducible builds for openSUSE (sponsored by the NLnet NGI0 fund), I found that
our openSUSE:Factory/python312 doc varied in html/library/audit_events.html in a strange way:

 <td><p><a class="reference internal" href="../reference/datamodel.html#href_anchor">[1]</a></p></td>
 </tr>
 <tr class="row-odd"><td><p>open</p></td>
-<td><p><code class="docutils literal notranslate"><span class="pre">path</span></code>, <code class="docutils literal notranslate"><span class="pre">mode</span></code>, <code class="docutils literal notranslate"><span class="pre">flags</span></code></p></td>
+<td><p><code class="docutils literal notranslate"><span class="pre">file</span></code>, <code class="docutils literal notranslate"><span class="pre">mode</span></code>, <code class="docutils literal notranslate"><span class="pre">flags</span></code></p></td>
 <td><p><a class="reference internal" href="functions.html#href_anchor">[1]</a><a class="reference internal" href="io.html#href_anchor">[2]</a><a class="reference internal" href="os.html#href_anchor">[3]</a></p></td>
 </tr>

According to strace, this file is written by a call to ["sphinx-build", "-b", "html", "-d", "build/doctrees", "-j", "auto", ".", "build/html"]

All build output should be deterministic.

CPython versions tested on:

3.10, 3.11, 3.12

Operating systems tested on:

Linux

Linked PRs
@bmwiedemann bmwiedemann added the type-bug An unexpected behavior, bug, or error label Jul 16, 2024
@bmwiedemann
Copy link
Contributor Author

My tools tell me, that the issue goes away, when both builds happen in 1-core-VMs, so it might be a race-condition.

@hugovk
Copy link
Member

hugovk commented Jul 16, 2024

Sounds like something to report to Sphinx.

https://github.com/sphinx-doc/sphinx

bmwiedemann added a commit to bmwiedemann/cpython that referenced this issue Jul 17, 2024
@bmwiedemann
Define audit-event open parameters consistently
20abe4d 
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.

Fixes: python#121874
bmwiedemann added a commit to bmwiedemann/cpython that referenced this issue Jul 17, 2024
@bmwiedemann
Define audit-event open parameters consistently
5406dce 
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: python#121874

This patch was done while working on reproducible builds for openSUSE, sponsored by the NLnet NGI0 fund.
@bmwiedemann bmwiedemann mentioned this issue Jul 17, 2024
Merged
@bmwiedemann
Copy link
Contributor Author

It is probably sphinx-doc/sphinx#2946 = sphinx-doc/sphinx#6714 - open since many years.
For now, #121883 helps to avoid the issue.

@hugovk hugovk changed the title doc: docs: inconsistent open and io.open audit-event parameters Jul 17, 2024
@hugovk hugovk added the docs Documentation in the Doc dir label Jul 17, 2024
bmwiedemann added a commit to bmwiedemann/cpython that referenced this issue Jul 17, 2024
@bmwiedemann
Define audit-event open parameters consistently
39696cf 
as in
Doc/library/functions.rst:   .. audit-event:: open file,mode,flags open
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: python#121874
Alternative to: python#121883

This patch was done while working on reproducible builds for openSUSE, sponsored by the NLnet NGI0 fund.
bmwiedemann added a commit to bmwiedemann/cpython that referenced this issue Jul 17, 2024
@bmwiedemann
Define audit-event open parameters consistently
dce9034 
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: python#121874

This patch was done while working on reproducible builds for openSUSE, sponsored by the NLnet NGI0 fund.
serhiy-storchaka pushed a commit that referenced this issue Jul 18, 2024
@bmwiedemann
gh-121874: Define audit-event open parameters consistently (GH-121883)
24cf867 
Use same names for parameters to avoid triggering a race-condition in Sphinx
that causes non-deterministic output.
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Jul 18, 2024
@bmwiedemann @miss-islington
pythongh-121874: Define audit-event open parameters consistently (pyt…
5c4bbbe 
…honGH-121883)

Use same names for parameters to avoid triggering a race-condition in Sphinx
that causes non-deterministic output.
(cherry picked from commit 24cf867)

Co-authored-by: Bernhard M. Wiedemann <[email protected]>
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Jul 18, 2024
@bmwiedemann @miss-islington
pythongh-121874: Define audit-event open parameters consistently (pyt…
9f3fb62 
…honGH-121883)

Use same names for parameters to avoid triggering a race-condition in Sphinx
that causes non-deterministic output.
(cherry picked from commit 24cf867)

Co-authored-by: Bernhard M. Wiedemann <[email protected]>
This was referenced Jul 18, 2024
Merged
Merged
serhiy-storchaka pushed a commit that referenced this issue Jul 18, 2024
@miss-islington @bmwiedemann
[3.12] gh-121874: Define audit-event open parameters consistently (GH…
1d915aa 
…-121883) (GH-121955)

Use same names for parameters to avoid triggering a race-condition in Sphinx
that causes non-deterministic output.
(cherry picked from commit 24cf867)

Co-authored-by: Bernhard M. Wiedemann <[email protected]>
hugovk added a commit that referenced this issue Aug 9, 2024
@miss-islington @bmwiedemann @hugovk
[3.13] gh-121874: Define audit-event open parameters consistently (GH…
406f924 
…-121883) (#121956)

Co-authored-by: Bernhard M. Wiedemann <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
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 type-bug An unexpected behavior, bug, or error
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

gh-121874: Define audit-event open parameters consistently bmwiedemann/cpython
2 participants
@bmwiedemann @hugovk