[docs] [issue24013] Improve os.scandir() and DirEntry documentation

[Ben Hoyt]

New submission from Ben Hoyt:

Victor Stinner's documentation for os.scandir and DirEntry is a great start (https://docs.python.org/dev/library/os.html#os.scandir), however there are a few mistakes in it, and a few ways I think it could be improved. Attaching a patch with the following overall changes:

1. Tweak the "see also" note on os.listdir() to mention *why* you'd want to use scandir -- namely that it includes file attribute info, and performance.
2. Move that str/bytes note in the scandir() docs down a bit, as I think that's really a detail and the other stuff is more important.
3. More details on why you'd want to use scandir -- to "increase the performance of code that also needs file type or file" -- and be more specific about what system calls are and are not required.
4. Replace "POSIX" with "Unix", per the rest of the os module docs when talking about generic Unix-like operating systems. It seems "POSIX" is used specifically when talking about the POSIX standard.
5. Remove half-true statement in DirEntry docs, "if a file is deleted between calling scandir and stat, a FileNotFoundError can be raised" -- but the method docs state that they specifically don't raise FileNotFoundError.
6. Removed "unfortunately, the behaviour of errors depends on the platform". This is always the case and doesn't add anything.
7. Tried to simplify and clarify the is_dir() and is_file() docs. Not sure I've succeeded here. This is hard!
8. Added "Availability: Unix, Windows." to scandir docs like listdir and most other os functions have.
9. Remove the see also about how "the listdir function returns the names of the directory entries" as that's already stated/implied above.

----------
assignee: docs at python
components: Documentation
files: scandir_doc_tweaks.patch
keywords: patch
messages: 241560
nosy: benhoyt, docs at python, haypo, serhiy.storchaka
priority: normal
severity: normal
status: open
title: Improve os.scandir() and DirEntry documentation
versions: Python 3.5
Added file: http://bugs.python.org/file39131/scandir_doc_tweaks.patch

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