[docs] [issue26248] Improve scandir DirEntry docs, especially re symlinks and caching

[Ben Hoyt]

New submission from Ben Hoyt:

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.

----------
assignee: docs at python
components: Documentation
files: direntry_doc_improvements.patch
keywords: patch
messages: 259282
nosy: benhoyt, docs at python, gvanrossum, haypo, serhiy.storchaka
priority: normal
severity: normal
status: open
title: Improve scandir DirEntry docs, especially re symlinks and caching
versions: Python 3.5, Python 3.6
Added file: http://bugs.python.org/file41765/direntry_doc_improvements.patch

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