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 os.scandir() and DirEntry documentation
Type: Stage: resolved
Components: Documentation Versions: Python 3.5
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: benhoyt, docs@python, python-dev, serhiy.storchaka, vstinner
Priority: normal Keywords: patch

Created on 2015-04-19 20:01 by benhoyt, last changed 2022-04-11 14:58 by admin. This issue is now closed.

File name Uploaded Description Edit
scandir_doc_tweaks.patch benhoyt, 2015-04-19 20:01 Proposed changes to scandir and DirEntry docs review
Messages (3)
msg241560 - (view) Author: Ben Hoyt (benhoyt) * Date: 2015-04-19 20:01
Victor Stinner's documentation for os.scandir and DirEntry is a great start (, 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.
msg243251 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-05-15 07:13
New changeset e7c7431f91b2 by Victor Stinner in branch 'default':
Closes #24013: Improve os.scandir() and DirEntry documentation
msg243252 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2015-05-15 07:14
> 8. Added "Availability: Unix, Windows." to scandir docs like listdir and most other os functions have.

That's wrong: availability should only be explained when a function is not always available. os.listdir() and os.scandir() are always available. I made the opposite change: I removed the availability information from os.listdir() and many other os functions in the changeset 77ebd3720284.

Thanks Ben, I applied your patch (except of the Availability line).
Date User Action Args
2022-04-11 14:58:15adminsetgithub: 68201
2015-05-15 07:14:50vstinnersetmessages: + msg243252
2015-05-15 07:13:13python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg243251

resolution: fixed
stage: resolved
2015-04-19 20:01:51benhoytcreate