classification
Title: Improve scandir DirEntry docs, especially re symlinks and caching
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: benhoyt, docs@python, gvanrossum, python-dev, serhiy.storchaka, vstinner
Priority: normal Keywords: patch

Created on 2016-01-31 16:43 by benhoyt, last changed 2016-03-18 16:20 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
direntry_doc_improvements.patch benhoyt, 2016-01-31 16:43 review
Messages (7)
msg259282 - (view) Author: Ben Hoyt (benhoyt) * Date: 2016-01-31 16:43
Per Guido's comment about DirEntry documentation on Issue 26032, especially http://bugs.python.org/issue26032#msg257665, it'd be good to improve the docs of the scandir DirEntry methods with regard to symlinks and caching.

Attaching my stab at a documentation fix. Changes here are:

1) Clarify that the return values of is_dir()/is_file()/etc are cached separately for follow_symlinks True and False.
2) Be more specific about when the functions require a system call, and how it relates to caching and follow_symlinks.
3) DRY up common stuff between is_dir and is_file by saying "Caching, system calls made, and exceptions raised are as per is_dir" in is_file.
4) Tweak to the first paragraph of docs for is_dir/is_file to simplify: assume the follow_symlinks=True default, then note the follow_symlinks=False non-default case after.

I think they're all improvements, though I'm not sure about #3. Is it better to just repeat those couple of paragraphs verbatim?

I'm also not 100% sure about mentioning the DT_UNKNOWN thing. But you really can't get more specific about when system calls are required on Unix without mentioning it.
msg259287 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-01-31 17:37
New changeset f2c68cb17e31 by Victor Stinner in branch '3.5':
Enhance os.scandir() doc
https://hg.python.org/cpython/rev/f2c68cb17e31
msg259288 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2016-01-31 17:40
The change looks good to me. I pushed it to 3.5 & 3.6. It will be online in a few hours at:
https://docs.python.org/dev/library/os.html#os.DirEntry

I keep the issue open a few days to see if some others have other suggestions.
msg259325 - (view) Author: Ben Hoyt (benhoyt) * Date: 2016-02-01 14:18
Thanks, Victor!
msg259658 - (view) Author: Ben Hoyt (benhoyt) * Date: 2016-02-05 13:03
Seeing this has been merged (thanks Victor), can this issue be closed? Guido, are you happy with the changes given your comments at http://bugs.python.org/issue26032#msg257665?
msg259661 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2016-02-05 14:04
Ben Hoyt added the comment:
> Seeing this has been merged (thanks Victor), can this issue be closed?

As I wrote, I left the issue open for wait for feedback. I know that
some people to read the doc online:
https://docs.python.org/dev/library/os.html#os.DirEntry
msg259691 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2016-02-05 21:25
Thanks very much for all that added information!
History
Date User Action Args
2016-03-18 16:20:07ezio.melottisettype: enhancement
stage: resolved
2016-02-05 21:25:03gvanrossumsetstatus: open -> closed
resolution: fixed
messages: + msg259691
2016-02-05 14:04:45vstinnersetmessages: + msg259661
2016-02-05 13:03:36benhoytsetmessages: + msg259658
2016-02-01 14:18:10benhoytsetmessages: + msg259325
2016-01-31 17:40:25vstinnersetmessages: + msg259288
2016-01-31 17:37:46python-devsetnosy: + python-dev
messages: + msg259287
2016-01-31 16:43:42benhoytcreate