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.

classification
Title: Documentation links for io.open
Type: Stage: needs patch
Components: Documentation Versions: Python 3.3
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, gsingh, loewis, python-dev, terry.reedy
Priority: normal Keywords:

Created on 2013-03-14 15:02 by gsingh, last changed 2022-04-11 14:57 by admin.

Messages (6)
msg184166 - (view) Author: Gurmeet Singh (gsingh) Date: 2013-03-14 15:02
Incompletely explained documentation at 2 places:

1. http://docs.python.org/3/library/functions.html#open

The buffering argument is not correctly explained when setting to a positive argument in binary mode.

2. http://docs.python.org/3/library/os.html#os.open

It is not very clear where to find descriptions of the arguments of this function. Where to find the required information and where to find C run-time documentation could be explained in following preferably:
(Python/C API Reference Manual) http://docs.python.org/3/c-api/index.html and / or 
(The Python Standard Library) http://docs.python.org/3/library and  / or 
(Python Runtime Services) http://docs.python.org/3/library/python.html 

A hyperlink may be added if so felt.
msg184276 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-03-15 23:05
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.
msg184327 - (view) Author: Gurmeet Singh (gsingh) Date: 2013-03-16 16:10
Please read the comment completely.

For the first point
___________________
I apologize that there was no mistake in binary mode and I have read it hastily. There is no ambiguity in the binary mode as you said. Reading hastily, I felt '...(only usable in text mode)... applies to all positive values, not just for the case of one. I was wrong there. 

However, text mode buffering description is not clear. Does the positive non unity buffer size value indicates the number of lines or the size in bytes or size of string characters (as per the system encoding) etc. This description could be made clearer (for both the text as well as the binary modes)

I also want to say that buffering is working incorrectly. In fact it is not working at all on windows x86 (I am raising a separate issue for this since that is not a documentation issue). 

For the second point (My answer here is for Windows part only)
____________________
The hyperlink http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx could be great instead of see C-run time documentation. It explains both "flag" as well as "mode". Actually this is the hyperlink given in the page you mentioned (http://docs.python.org/3/library/os.html#open-flag-constants) - I guess I gave up on this link, since I felt function was largely undocumented and useless.

I really "request" you to mention that C runtime library specification is actually http://msdn.microsoft.com/en-us/library/59ey50w6.aspx - I accidentally found this - there is no simple way (without reading extensively, I guess) to know that Python is actually using Microsoft VC++ at the backend and that the runtime library of that would be of that. So you could mention this on the introductory pages that C-API/Library is actually http://msdn.microsoft.com/en-us/library/59ey50w6.aspx.

_______________________________________________________________
P.S. Please (at least) see my comment on the other documentation ambiguity issue that you have closed already.
msg184331 - (view) Author: Gurmeet Singh (gsingh) Date: 2013-03-16 16:38
The issue with buffering problem mentioned in my previous comment has been raised as issue 17440. 
However, I need to apologize again! The statement that buffering is not implemented at all was incorrect - instead read1() was not implemented. See the mentioned issue for more details.
msg184348 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-03-16 20:08
New changeset f334a0009586 by Terry Jan Reedy in branch '2.7':
Issue #17418: specify that buffer sizes are bytes.
http://hg.python.org/cpython/rev/f334a0009586

New changeset a9d54ba2370b by Terry Jan Reedy in branch '3.2':
Issue #17418: specify that buffer sizes are bytes as soon as possible.
http://hg.python.org/cpython/rev/a9d54ba2370b
msg184350 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-03-16 20:14
Most people should know that os i/o buffers are always bytes. But since beginners read the built-in functions page, I augmented the open() entry, which is what you linked to. I will not change the entries in the io module chapter. I consider this part of the issue closed. That leaves the entry for os.open. I changed the title accordingly.
History
Date User Action Args
2022-04-11 14:57:42adminsetstatus: pending -> open
github: 61620
2017-10-28 12:06:46serhiy.storchakasetstatus: open -> pending
2013-03-16 20:14:21terry.reedysetmessages: + msg184350
title: Documentation for os.open and io.open -> Documentation links for io.open
2013-03-16 20:08:47python-devsetnosy: + python-dev
messages: + msg184348
2013-03-16 16:38:36gsinghsetmessages: + msg184331
2013-03-16 16:10:23gsinghsetmessages: + msg184327
2013-03-15 23:05:33terry.reedysetnosy: + loewis, terry.reedy
title: Documentation Bug -> Documentation for os.open and io.open
messages: + msg184276

stage: needs patch
2013-03-14 15:02:41gsinghcreate