[adorilson]

This PR makes the documentation more suitable with the functions definitions in the source code and removes a inconsistency when the reader reads file in the functions assignature, but the first line below cites path.

---

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

[picnixz]

The reason why spawn uses path is probably because it handles its argument similarly to how posix_spawn does in C.

The only difference between posix_spawn() and posix_spawnp() is the manner in which they specify the
file to be executed by the child process. With posix_spawn(), the executable file is specified as a
pathname (which can be absolute or relative). With posix_spawnp(), the executable file is specified
as a simple filename; the system searches for this file in the list of directories specified by PATH
(in the same way as for execvp(3))

In particular, the semantics of path and file are distinct. Concerning the code source of Python itself, I think that's the one that should be changed (and not the docs themselves in this case).

However, we could be a bit more precise in the docs (but for that, I'd check the C code first).

[adorilson]

Concerning the code source of Python itself, I think that's the one that should be changed (and not the docs themselves in this case).

Here the problem is the consequences. See this @gpshead's comment: https://discuss.python.org/t/is-time-to-remove-os-module-spawn-functions/55829/7

[picnixz]

Oh actually I got misleaded! Actually, those ones have indeed nothing to do with posix_* but they actually seem to use the same conventions:

The variants which include a second “p” near the end (spawnlp(), spawnlpe(), spawnvp(), and spawnvpe()) will use the PATH environment variable to locate the program file. When the environment is being replaced (using one of the spawn*e variants, discussed in the next paragraph), the new environment is used as the source of the PATH variable. The other variants, spawnl(), spawnle(), spawnv(), and spawnve(), will not use the PATH variable to locate the executable; path must contain an appropriate absolute or relative path.

While my previous comment was incorrect, the rationale of why those names were used is probably what I thought about.

[adorilson]

While my previous comment was incorrect, the rationale of why those names were used is probably what I thought about.

The problem is not in the function definition. There all spawn function uses file. The problem is only in the documentation at docs.python.org. The documentation strings are correct.

A similar problem occurs with os.startfile, where there is another PR.

[github-actions]

This PR is stale because it has been open for 30 days with no activity.

[encukou]

The semantics of the p variants are explained appropriately in the text.
The argument name is file, which means this works:

>>> os.spawnv(mode=os.P_WAIT, file='/usr/bin/echo', args=['echo', 'hi'])
hi
0

but this doesn't:

>>> os.spawnv(mode=os.P_WAIT, path='/usr/bin/echo', args=['echo', 'hi'])
Traceback (most recent call last):
  File "<python-input-12>", line 1, in <module>
    os.spawnv(mode=os.P_WAIT, path='/usr/bin/echo', args=['echo', 'hi'])
    ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TypeError: spawnv() got an unexpected keyword argument 'path'

Arguably, no one would rely on that detail. Still, it's better if the docs are correct :)

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #35648178 | 📁 Comparing 167a3e3 against main (1dd8e71)

  🔍 Preview build  

2 files changed

± library/audit_events.html
± library/os.html

[miss-islington-app]

Thanks @adorilson for the PR, and @encukou for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14, 3.15.
🐍🍒⛏🤖

[bedevere-app]

GH-161412 is a backport of this pull request to the 3.15 branch.

[bedevere-app]

GH-161413 is a backport of this pull request to the 3.14 branch.