[New-bugs-announce] [issue13143] os.path.islink documentation is ambiguous

[Garen]

New submission from Garen <garen.parham at gmail.com>:

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.

----------
messages: 145290
nosy: Garen
priority: normal
severity: normal
status: open
title: os.path.islink documentation is ambiguous
versions: Python 2.7, Python 3.2

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13143>
_______________________________________