[issue13143] os.path.islink documentation is ambiguous

[Roundup Robot]

Roundup Robot added the comment:

New changeset f463387d2434 by Benjamin Peterson in branch '2.7':
clarify that islink only really works if python knows about symlinks (closes 
#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 
#13143)
http://hg.python.org/cpython/rev/db7887f3e6a2

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

--
nosy: +python-dev
resolution:  -> fixed
stage: needs patch -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13143] os.path.islink documentation is ambiguous

[Yayoi Ukai]

Yayoi Ukai added the comment:

Documentation is updated to be more clear

--
keywords: +patch
nosy: +terab
Added file: http://bugs.python.org/file35515/mywork.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13143] os.path.islink documentation is ambiguous

[Ezio Melotti]

Ezio Melotti  added the comment:

> 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.

--
components: +Documentation
nosy: +ezio.melotti
stage:  -> needs patch
versions: +Python 3.3

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13143] os.path.islink documentation is ambiguous

[Jason R. Coombs]

Jason R. Coombs  added the comment:

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.

--
assignee:  -> jason.coombs

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13143] os.path.islink documentation is ambiguous

[Eric V. Smith]

Changes by Eric V. Smith :


--
nosy: +eric.smith, jason.coombs

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue13143] os.path.islink documentation is ambiguous

[Garen]

New submission from 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.

--
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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com