os.path.islink documentation is ambiguous

[Garen]

BPO	13143
Nosy	@jaraco, @ericvsmith, @ezio-melotti
Files	mywork.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/jaraco'
closed_at = <Date 2014-06-23.01:00:14.225>
created_at = <Date 2011-10-10.04:35:02.707>
labels = ['docs']
title = 'os.path.islink documentation is ambiguous'
updated_at = <Date 2014-06-23.01:00:14.223>
user = 'https://bugs.python.org/Garen'

bugs.python.org fields:

activity = <Date 2014-06-23.01:00:14.223>
actor = 'python-dev'
assignee = 'jaraco'
closed = True
closed_date = <Date 2014-06-23.01:00:14.225>
closer = 'python-dev'
components = ['Documentation']
creation = <Date 2011-10-10.04:35:02.707>
creator = 'Garen'
dependencies = []
files = ['35515']
hgrepos = []
issue_num = 13143
keywords = ['patch']
message_count = 5.0
messages = ['145290', '145299', '145301', '219955', '221332']
nosy_count = 6.0
nosy_names = ['jaraco', 'eric.smith', 'ezio.melotti', 'Garen', 'python-dev', 'terab']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue13143'
versions = ['Python 2.7', 'Python 3.2', 'Python 3.3']

[Garen]

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:

PythonWin 2.7.2 (default, Jun 24 2011, 12:21:10) [MSC v.1500 32 bit (Intel)] on win32.
Portions Copyright 1994-2008 Mark Hammond - see 'Help/About PythonWin' for further copyright information.
>>> 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.

[jaraco]

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.

[ezio-melotti]

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.

[terab]

Documentation is updated to be more clear

[python-dev]

New changeset f463387d2434 by Benjamin Peterson in branch '2.7':
clarify that islink only really works if python knows about symlinks (closes bpo-13143)
http://hg.python.org/cpython/rev/f463387d2434

New changeset db7887f3e6a2 by Benjamin Peterson in branch '3.4':
clarify that islink only really works if python knows about symlinks (closes bpo-13143)
http://hg.python.org/cpython/rev/db7887f3e6a2

New changeset 81529993f60d by Benjamin Peterson in branch 'default':
merge 3.4 (bpo-13143)
http://hg.python.org/cpython/rev/81529993f60d