[issue17418] Documentation Bug
New submission from Gurmeet Singh: 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. ---------- assignee: docs@python components: Documentation messages: 184166 nosy: docs@python, gsingh priority: normal severity: normal status: open title: Documentation Bug versions: Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17418> _______________________________________
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@bugs.python.org> <http://bugs.python.org/issue17418> _______________________________________
Gurmeet Singh added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17418> _______________________________________
Gurmeet Singh added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17418> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17418> _______________________________________
Terry J. Reedy added the comment: 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. ---------- title: Documentation for os.open and io.open -> Documentation links for io.open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17418> _______________________________________
Change by Serhiy Storchaka <storchaka+cpython@gmail.com>: ---------- status: open -> pending _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue17418> _______________________________________
participants (4)
-
Gurmeet Singh -
Roundup Robot
-
Serhiy Storchaka
-
Terry J. Reedy