gh-72542: State that os.rename() always fails across filesystems on Windows

[MannXo]

The Windows paragraph of os.rename() says the operation "may fail" if src and dst are on different filesystems. On Windows it is a certainty, not a possibility, so this changes "may" to "will".

This is the wording eryksun asked for in the issue:

The documentation of os.rename() should mention that on Windows the "operation will fail if src and dst are on different filesystems". For POSIX, instead of "will" it says "may", but the failure is a certainty in Windows since MOVEFILE_COPY_ALLOWED isn't used.

That distinction is still accurate. Modules/posixmodule.c computes the MoveFileExW flags as int flags = is_replace ? MOVEFILE_REPLACE_EXISTING : 0, and MOVEFILE_COPY_ALLOWED does not appear anywhere in the file, so a cross-volume move always fails with ERROR_NOT_SAME_DEVICE. The Unix paragraph two paragraphs below keeps "may fail on some Unix flavors", which is correct there, and the contrast between the two is the point of the change.

A note on why this issue is still open. GH-27376 was merged and it added the cross-filesystem sentence, which is why it looks resolved at a glance, but it used "may" rather than the "will" that was requested. The sentence exists; only the strength of the claim is wrong.

One question

os.replace() has the same "may fail if src and dst are on different filesystems" sentence and shares the Windows code path, so the failure is equally certain there. Its paragraph is platform-neutral, though, and the issue only discussed os.rename(), so I left it alone rather than widening the diff. Happy to add a Windows note there in this PR if you would prefer.

Verification

Built the docs with the nit-picky settings the Docs workflow uses:

make -C Doc/ venv
make -C Doc/ SPHINXOPTS="--quiet --nitpicky --warning-file sphinx-warnings.txt" html
python Doc/tools/check-warnings.py --fail-if-regression --fail-if-improved
sphinx-lint --enable=default-role Doc/library/os.rst

check-warnings.py and sphinx-lint both exit 0, and sphinx-warnings.txt contains no warnings for Doc/library/os.rst. Confirmed in the rendered library/os.html that the Windows paragraph reads "The operation will fail" while the Unix paragraph still reads "may fail on some Unix flavors".

No Misc/NEWS.d entry, since this is documentation only.

• Issue: [easy doc] Document os.rename() behavior on Windows when src and dst are on different filesystems #72542

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33794280 | 📁 Comparing 41d172d against main (a85830c)

  🔍 Preview build  

1 file changed

± library/os.html