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

[STINNER Victor]

STINNER Victor added the comment:

> 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).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Roundup Robot]

Roundup Robot added the comment:

New changeset e7c7431f91b2 by Victor Stinner in branch 'default':
Closes #24013: Improve os.scandir() and DirEntry documentation
https://hg.python.org/cpython/rev/e7c7431f91b2

--
nosy: +python-dev
resolution:  -> fixed
stage:  -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[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@python
components: Documentation
files: scandir_doc_tweaks.patch
keywords: patch
messages: 241560
nosy: benhoyt, docs@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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com