Improve scandir DirEntry docs, especially re symlinks and caching

[benhoyt]

BPO	26248
Nosy	@gvanrossum, @vstinner, @benhoyt, @serhiy-storchaka
Files	direntry_doc_improvements.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 = None
closed_at = <Date 2016-02-05.21:25:03.751>
created_at = <Date 2016-01-31.16:43:42.486>
labels = ['type-feature', 'docs']
title = 'Improve scandir DirEntry docs, especially re symlinks and caching'
updated_at = <Date 2016-03-18.16:20:07.690>
user = 'https://github.com/benhoyt'

bugs.python.org fields:

activity = <Date 2016-03-18.16:20:07.690>
actor = 'ezio.melotti'
assignee = 'docs@python'
closed = True
closed_date = <Date 2016-02-05.21:25:03.751>
closer = 'gvanrossum'
components = ['Documentation']
creation = <Date 2016-01-31.16:43:42.486>
creator = 'benhoyt'
dependencies = []
files = ['41765']
hgrepos = []
issue_num = 26248
keywords = ['patch']
message_count = 7.0
messages = ['259282', '259287', '259288', '259325', '259658', '259661', '259691']
nosy_count = 6.0
nosy_names = ['gvanrossum', 'vstinner', 'benhoyt', 'docs@python', 'python-dev', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue26248'
versions = ['Python 3.5', 'Python 3.6']

[benhoyt]

Per Guido's comment about DirEntry documentation on bpo-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.

[python-dev]

New changeset f2c68cb17e31 by Victor Stinner in branch '3.5':
Enhance os.scandir() doc
https://hg.python.org/cpython/rev/f2c68cb17e31

[vstinner]

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.

[benhoyt]

Thanks, Victor!

[benhoyt]

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?

[vstinner]

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

[gvanrossum]

Thanks very much for all that added information!