os.rename documentation about atomic replace misleading

[b-jonas0]

The documentation about os.rename https://docs.python.org/3/library/os.html#os.rename says the following about Unix:

If successful, the renaming will be an atomic operation (this is a POSIX requirement).

But this sentence is misleading. The rename call is atomic only in that the new filename (given by the dst parameter) will always point to either the old file or new file, with no intermediate state. In particular, if you replace an existing file name, then there won't be an observable state when that file name appears deleted. The rename does not act atomically on the old and new filenames together, as in it may happen that both the old name and new name could point to the same file at the same time. I don't think there was ever a requirement for rename to be atomic in the latter sense.

I'm not sure what the best phrasing for the documentation would be. Perhaps something like this:

The new filename dst is updated atomically (this is a POSIX requirement).

Linked PRs

• Doc: clarify os.rename doesn't atomically replace dst contents (gh-143909) #143937

[a12k]

Yeah this is correct. Maybe you can change it to to hammer the point home:

On Unix, if dst exists, its replacement is atomic (a POSIX requirement). This ensures that dst is never missing; any process accessing the path will find either the original file or the new file.

[Yashp002]

Confirmed the docs issue—os.rename(src, dst) claims atomic replacement when dst exists, but Unix impl leaves old dst contents briefly accessible via race (new dst appears first, old deleted after).

Will fix docs to clarify: atomic w.r.t. filesystem namespace (dst path never missing), not content replacement (old data may linger til unlink)

[picnixz]

I do not think it warrants a huge change. If something needs to be done, it should be concise. What does the rename command say? or is there some mention of this atomicity in the POSIX specs? maybe we could use their formulation