[docs] [issue17418] Documentation for os.open and io.open

[Terry J. Reedy]

Terry J. Reedy added the comment:

This is really two issues:

io.open: Your statement about *buffering* not correct is not helpful. Quote the sentence you think is wrong. I am guessing it is "Pass ... an integer > 1 to indicate the size of a fixed-size chunk buffer". Then quote some code from the module or code that uses the module that acts differently from the doc. Then suggest an alternative wording supported by the evidence presented.

os.open:
For *flags*, there already is a link to
http://docs.python.org/3/library/os.html#open-flag-constants
That says "consult the open(2) manual page on Unix or the MSDN on Windows."

I believe mode is ignored on Windows. (Martin, true?)
Any Unix system should document the various bits, but we could say where, as with flags (open(2) also)?

I agree that "see the C run-time documentation" (for flags and mode) is pretty useless as is. This must refer to the C-API manual.  If you can find a specific link for info about flags or mode, it can be added. I do not see anything in the index. It is possible that the sentence is obsolete and should be deleted.

Do note that the note "This function is intended for low-level I/O. For normal usage, use the built-in function open()," strongly implies that one should only use this function with some understanding of the os function that it wraps. This is true for much of the os module.

----------
nosy: +loewis, terry.reedy
stage:  -> needs patch
title: Documentation Bug -> Documentation for os.open and io.open

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