Issue 13143: os.path.islink documentation is ambiguous (original) (raw)

The documentation for os.path.islink says:

"Return True if path refers to a directory entry that is a symbolic link. Always False if symbolic links are not supported."

But what does "supported" mean? "Supported" by what? Supported by the OS, or supported by the Python runtime? Because clearly there is a difference, which surprised me:

import os os.path.islink(r"C:\Users\Garen\dev\pypy.exe") False os.path.islink(r"C:\Users\Garen\dev\abspypy.exe") False

Whereas if I use 3.2.x, I get the right answers: ActivePython 3.2.2.3 (ActiveState Software Inc.) based on Python 3.2.2 (default, Sep 8 2011, 10:56:38) [MSC v.1500 32 bit (Intel)] on win32 Type "copyright", "credits" or "license()" for more information.

import os os.path.islink(r"C:\Users\Garen\dev\pypy.exe") True os.path.islink(r"C:\Users\Garen\dev\abspypy.exe") True

An additional surprise is that in other places of the Python runtime, if functionality is not implemented for Windows, an exception of type NotImplementedError is raised--but not in this case with os.path.islink().

This all makes it a hairy mess to properly detect symlinks--from the client code perspective, now one has to check for specific versions of python, specific versions of Windows, and possibly which file-system is being used (FAT vs NTFS) just to be able to determine if islink() is silently failing or not. After which the client side will want to add clarifying comments to compensate for what's missing from the official docs (as opposed to posting a link to the docs in a comment).

As a user from the client side, I would only expect os.path.islink() to return False if the underlying OS/filesystem didn't support symlinks; if the underlying OS/filesystem did suport symlinks but support was missing, I'd expect to see a NoteImplementedError raised.

In any case, where behavior for os.path.islink() (and related routines) deviates from the above pattern, I'd expect documentation that indicates what those deviations are--in this case, that False means unsupported by the Python runtime regardless of whether the OS/filesystem provides that functionality.

Thanks Garen for the detailed analysis and writeup. The short answer to your question is "supported by the Python runtime". Allow me to provide a bit of history.

Symlink awareness under Windows was added to Python in Python 3.2, so the behavior you see in Python 2.7 is somewhat historical - in particular, islink was implemented to always return False. In hindsight, this decision was probably a poor one, because it doesn't allow for forward compatibility.

Unfortunately, due to the compatibility rules of Python versions, this cannot change. The semantic meaning of ntpath.islink (and thus os.path.islink on Windows) cannot change.

The suggestion to update the documentation to reflect this behavior is a good one. I will extend the Python 3.1 and earlier docs to clarify this detail.

One suggestion for the client: to accurately determine if the Python runtime supports symlinks, check hasattr(os, 'symlink'), whereafter you'll know if the runtime supports symlinks and whether os.link will return anything other than False.

Symlink awareness under Windows was added to Python in Python 3.2

If they are not available on Windows with 2.7, the doc should get an "availability: unix" or something similar (depending on where they are actually supported), or mention explicitly symlink for Windows are not supported.

I will extend the Python 3.1 and earlier docs to clarify this detail.

3.1 only gets security fixes, so only 2.7/3.2/default should be updated.