Confusing wording in `os.path.lexists` docs

[pfortin]

os.path.lexists(path) https://docs.python.org/3/library/os.path.html#os.path.lexists

Return True if path refers to an existing path. Returns **True** for broken symbolic links. Equivalent to [exists()](https://docs.python.org/3/library/os.path.html#os.path.exists) on platforms lacking [os.lstat()](https://docs.python.org/3/library/os.html#os.lstat).

Should read False

Linked PRs

• gh-117360: Improve os.path.lexists documentation #117679
• [3.12] gh-117360: Clearer wording in os.path.lexists() docs (GH-117679) #117701

[eryksun]

os.path.lexists() doesn't follow symlinks, so it returns True for a broken symlink. Use os.path.exists() if you need False for a broken symlink.

[pfortin]

But what is the purpose of a function that only returns True?

[eryksun]

os.path.lexists() returns True only if path exists, regardless of the file type. It's useful when one needs to know whether anything with the given name exists, regardless of whether it's a regular file, directory, symlink, named pipe/socket, or device.

[terryjreedy]

If the doc matches the behavior, there is no bug. If the behavior is intended, and useful, we are unlikely to change it. Feature changes usually need be be discussed on discuss/ideas.

[zware]

As already explained, there's no bug in the docs or implementation here. However, we might be able to clarify the docs a bit: I think the confusion here came from the fact that the broken symlink case is called out explicitly in a separate sentence:

cpython/Doc/library/os.path.rst

Lines 148 to 149 in 01bd74e

	Return ``True`` if *path* refers to an existing path. Returns ``True`` for
	broken symbolic links. Equivalent to :func:`exists` on platforms lacking

This reads a bit clearer to me:

Return True if path refers to an existing path, including broken symbolic links.

[erlend-aasland]

Resolved by:

• gh-117360: Improve os.path.lexists documentation #117679
• [3.12] gh-117360: Clearer wording in os.path.lexists() docs (GH-117679) #117701 (auto-merge enabled)