This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Improve scandir DirEntry docs, especially re symlinks and caching
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5
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 2022-04-11 14:58 by admin. This issue is now closed.

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

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
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:
msg259691 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2016-02-05 21:25
Thanks very much for all that added information!
Date User Action Args
2022-04-11 14:58:27adminsetgithub: 70436
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