[issue11352] Buf in cgi module doc
New submission from Pierre Quentel <pierre.quentel@gmail.com>: Hi, I wrote a patch for the cgi module in version 3.2rc1 (#4953). Small changes should be done to the documentation of this module to reflect the changes in the module API : - in section "20.2.2. Using the cgi module" original text : "If a field represents an uploaded file, accessing the value via the value attribute or the getvalue() method reads the entire file in memory as a string. This may not be what you want. You can test for an uploaded file by testing either the filename attribute or the file attribute. You can then read the data at leisure from the file attribute:" proposed new text (for files, value is bytes, not string, and the read() method on file also returns bytes) : "If a field represents an uploaded file, accessing the value via the value attribute or the getvalue() method reads the entire file in memory as bytes. This may not be what you want. You can test for an uploaded file by testing either the filename attribute or the file attribute. You can then read the data at leisure from the file attribute (the read() and readline() methods will return bytes) :" - version 3.2 introduced a parameter "encoding" for the FieldStorage constructor, used to decode the bytes received on the HTTP connection for fields other than files. This encoding must the one defined in the HTML document holding the form submitted to the CGI script ; it is usually defined by a meta tag : <meta http-equiv="Content-type" content="text/html;charset=latin-1"> or by the Content-Type header for this document I'm not sure where this should be mentioned in the module documentation. Maybe in "20.2.9. Common problems and solutions" for the moment. But there are plans (#11066) to introduce another interface to change the encoding of sys.stdout in the CGI script itself, so another option would be to open a specific section about encodings Hope it's clear enough Pierre ---------- assignee: docs@python components: Documentation messages: 129691 nosy: docs@python, quentel priority: normal severity: normal status: open title: Buf in cgi module doc type: behavior versions: Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Pierre Quentel <pierre.quentel@gmail.com> added the comment: "bug", not "buf"... ---------- title: Buf in cgi module doc -> Bug in cgi module doc _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- keywords: +needs review, patch nosy: +amaury.forgeotdarc, andyharrington, erob, flox, gagenellina, haypo, oopos, pebbe, r.david.murray, tcourbon, tobias, v+python priority: normal -> high stage: -> patch review title: Bug in cgi module doc -> Update cgi module doc type: behavior -> versions: +Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Hynek Schlawack <hs@ox.cx> added the comment: What is the reason for this one to languish for over a year now? Lack of proper patch? It’s marked “high priority”, so let’s get moving. ---------- nosy: +hynek, sandro.tosi _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Changes by Senthil Kumaran <senthil@uthcode.com>: ---------- assignee: docs@python -> orsenthil nosy: +orsenthil _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
STINNER Victor <victor.stinner@gmail.com> added the comment:
What is the reason for this one to languish for over a year now?
Maybe because few people are concerned by the cgi module?
Lack of proper patch?
It would help to have a patch attached to the issue, and a review of the patch. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Pierre Quentel <pierre.quentel@gmail.com> added the comment: Thanks Hynek for raising this issue from the dead Patch proposal attached. Sorry if there are markup errors, it's my first contact with rst ---------- Added file: http://bugs.python.org/file25416/cgi.rst _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Hynek Schlawack <hs@ox.cx> added the comment: That’s not a patch. :) Posting whole files makes them very hard to review because you can’t spot the changes. The best thing would be to get a fresh clone of the repo: http://docs.python.org/devguide/setup.html#setup , copy your edited file to the appropriate place and run `hg diff`. If it looks okay, redirect the output into a file (something like `hg diff >cgi-doc-update.patch`) and attach it to this issue. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Pierre Quentel <pierre.quentel@gmail.com> added the comment: Sorry about that. I didn't dare to say I was also a Mercurial newbie ---------- Added file: http://bugs.python.org/file25421/cgi-doc-update.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Senthil Kumaran <senthil@uthcode.com> added the comment: Not to worry about that Pierre. I shall review the patch (contents) in the evening (SGT) and I should be able to commit/close this issue. Thanks, Senthil ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Changes by Pierre Quentel <pierre.quentel@gmail.com>: Removed file: http://bugs.python.org/file25416/cgi.rst _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Pierre Quentel <pierre.quentel@gmail.com> added the comment: Thanks Senthil I spot a typo in the first modified paragraph : "cet" instead of "set" ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Roundup Robot <devnull@psf.upfronthosting.co.za> added the comment: New changeset a54b6e321f1c by Senthil Kumaran in branch '3.2': Issue11352 - Update cgi module docs http://hg.python.org/cpython/rev/a54b6e321f1c New changeset 910a4b12c796 by Senthil Kumaran in branch 'default': Issue11352 - Update cgi module docs http://hg.python.org/cpython/rev/910a4b12c796 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Senthil Kumaran <senthil@uthcode.com> added the comment: I have made the suggested specific changes, but while reviewing the entire doc, I realized that much improvements can be made. Keeping the documentation more helpful aligned with the cgi.py APIs. I shall keep bug report to update the cgi docs further. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Changes by Hynek Schlawack <hs@ox.cx>: ---------- nosy: -hynek _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Changes by Peter Kleiweg <pkleiweg@xs4all.nl>: ---------- nosy: -pebbe _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Pierre Quentel <pierre.quentel@gmail.com> added the comment: Hi, I started working on a revised version of the whole cgi documentation. I mostly changed paragraphs 2 & 3 ("Using the CGI module" and "Higher level interface") and replaced them by a paragraph still called "Using the CGI module" + 2 other paragraphs for special cases : "Multiple fields with the same name" and "File uploads" The content is basically the same but the new presentation is hopefully more clear The patch is attached as file cgi-doc.patch ---------- Added file: http://bugs.python.org/file25512/cgi-doc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Pierre Quentel <pierre.quentel@gmail.com> added the comment: I attach a new version after sharing thought with Glenn CGI scripts are still unable to define which encoding to use to print the strings received from the user agent. A patch was proposed #11066 but the issue is still pending. The new version documents this issue ---------- Added file: http://bugs.python.org/file25519/cgi-doc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Changes by A.M. Kuchling <lists@amk.ca>: ---------- nosy: +akuchling _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Jim Jewett added the comment: What is the status of this? Have any of the changes been applied? Are any of the other patches still appropriate? Is this now dependent on any other issues/any non-doc updates? ---------- nosy: +Jim.Jewett _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Berker Peksag added the comment:
Have any of the changes been applied?
A modified version of cgi-doc-update.patch was committed. (see msg159700) I left a couple of comments for cgi-doc.patch on Rietveld. ---------- nosy: +berker.peksag versions: +Python 3.4, Python 3.5 -Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Jim Jewett added the comment: I have now also looked at cgi-doc.patch, and it is not strictly documentation changes. I have no informed opinion on the the additional changes, but I don't think they should go in as "doc change". ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
R. David Murray added the comment: It looks like the non-doc stuff was accidental inclusions and should be ignored. Or better, the patch author could address Berker and Jim's comments and resubmit a clean patch. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Mark Lawrence added the comment: @Pierre can you submit a clean patch as requested in msg214267? ---------- nosy: +BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Changes by A.M. Kuchling <amk@amk.ca>: ---------- nosy: -akuchling _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Matthew Atkinson added the comment: Hi I've modified Pierre's patch to apply to the latest 3.5 and 3.4, and made the most of the simple changes suggested in http://bugs.python.org/review/11352/#ps4792 . I've also added all the non internal parameters to the FieldStorage constructor, and descriptions of them. Thanks, Matt ---------- nosy: +mutley89 Added file: http://bugs.python.org/file38026/cgi-doc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Changes by Ivan Levkivskyi <levkivskyi@gmail.com>: ---------- nosy: +levkivskyi _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Change by Mark Lawrence <breamoreboy@gmail.com>: ---------- nosy: -BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11352> _______________________________________
Pierre Quentel <pierre.quentel@gmail.com> added the comment: "bug", not "buf"... ---------- title: Buf in cgi module doc -> Bug in cgi module doc _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- keywords: +needs review, patch nosy: +amaury.forgeotdarc, andyharrington, erob, flox, gagenellina, haypo, oopos, pebbe, r.david.murray, tcourbon, tobias, v+python priority: normal -> high stage: -> patch review title: Bug in cgi module doc -> Update cgi module doc type: behavior -> versions: +Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Hynek Schlawack <hs@ox.cx> added the comment: What is the reason for this one to languish for over a year now? Lack of proper patch? It’s marked “high priority”, so let’s get moving. ---------- nosy: +hynek, sandro.tosi _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Changes by Senthil Kumaran <senthil@uthcode.com>: ---------- assignee: docs@python -> orsenthil nosy: +orsenthil _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
STINNER Victor <victor.stinner@gmail.com> added the comment:
What is the reason for this one to languish for over a year now?
Maybe because few people are concerned by the cgi module?
Lack of proper patch?
It would help to have a patch attached to the issue, and a review of the patch. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Pierre Quentel <pierre.quentel@gmail.com> added the comment: Thanks Hynek for raising this issue from the dead Patch proposal attached. Sorry if there are markup errors, it's my first contact with rst ---------- Added file: http://bugs.python.org/file25416/cgi.rst _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Hynek Schlawack <hs@ox.cx> added the comment: That’s not a patch. :) Posting whole files makes them very hard to review because you can’t spot the changes. The best thing would be to get a fresh clone of the repo: http://docs.python.org/devguide/setup.html#setup , copy your edited file to the appropriate place and run `hg diff`. If it looks okay, redirect the output into a file (something like `hg diff >cgi-doc-update.patch`) and attach it to this issue. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Pierre Quentel <pierre.quentel@gmail.com> added the comment: Sorry about that. I didn't dare to say I was also a Mercurial newbie ---------- Added file: http://bugs.python.org/file25421/cgi-doc-update.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Senthil Kumaran <senthil@uthcode.com> added the comment: Not to worry about that Pierre. I shall review the patch (contents) in the evening (SGT) and I should be able to commit/close this issue. Thanks, Senthil ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Changes by Pierre Quentel <pierre.quentel@gmail.com>: Removed file: http://bugs.python.org/file25416/cgi.rst _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Pierre Quentel <pierre.quentel@gmail.com> added the comment: Thanks Senthil I spot a typo in the first modified paragraph : "cet" instead of "set" ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Roundup Robot <devnull@psf.upfronthosting.co.za> added the comment: New changeset a54b6e321f1c by Senthil Kumaran in branch '3.2': Issue11352 - Update cgi module docs http://hg.python.org/cpython/rev/a54b6e321f1c New changeset 910a4b12c796 by Senthil Kumaran in branch 'default': Issue11352 - Update cgi module docs http://hg.python.org/cpython/rev/910a4b12c796 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Senthil Kumaran <senthil@uthcode.com> added the comment: I have made the suggested specific changes, but while reviewing the entire doc, I realized that much improvements can be made. Keeping the documentation more helpful aligned with the cgi.py APIs. I shall keep bug report to update the cgi docs further. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Changes by Hynek Schlawack <hs@ox.cx>: ---------- nosy: -hynek _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Changes by Peter Kleiweg <pkleiweg@xs4all.nl>: ---------- nosy: -pebbe _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Pierre Quentel <pierre.quentel@gmail.com> added the comment: Hi, I started working on a revised version of the whole cgi documentation. I mostly changed paragraphs 2 & 3 ("Using the CGI module" and "Higher level interface") and replaced them by a paragraph still called "Using the CGI module" + 2 other paragraphs for special cases : "Multiple fields with the same name" and "File uploads" The content is basically the same but the new presentation is hopefully more clear The patch is attached as file cgi-doc.patch ---------- Added file: http://bugs.python.org/file25512/cgi-doc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Pierre Quentel <pierre.quentel@gmail.com> added the comment: I attach a new version after sharing thought with Glenn CGI scripts are still unable to define which encoding to use to print the strings received from the user agent. A patch was proposed #11066 but the issue is still pending. The new version documents this issue ---------- Added file: http://bugs.python.org/file25519/cgi-doc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Changes by A.M. Kuchling <lists@amk.ca>: ---------- nosy: +akuchling _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Jim Jewett added the comment: What is the status of this? Have any of the changes been applied? Are any of the other patches still appropriate? Is this now dependent on any other issues/any non-doc updates? ---------- nosy: +Jim.Jewett _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Berker Peksag added the comment:
Have any of the changes been applied?
A modified version of cgi-doc-update.patch was committed. (see msg159700) I left a couple of comments for cgi-doc.patch on Rietveld. ---------- nosy: +berker.peksag versions: +Python 3.4, Python 3.5 -Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Jim Jewett added the comment: I have now also looked at cgi-doc.patch, and it is not strictly documentation changes. I have no informed opinion on the the additional changes, but I don't think they should go in as "doc change". ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
R. David Murray added the comment: It looks like the non-doc stuff was accidental inclusions and should be ignored. Or better, the patch author could address Berker and Jim's comments and resubmit a clean patch. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Mark Lawrence added the comment: @Pierre can you submit a clean patch as requested in msg214267? ---------- nosy: +BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Changes by A.M. Kuchling <amk@amk.ca>: ---------- nosy: -akuchling _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Matthew Atkinson added the comment: Hi I've modified Pierre's patch to apply to the latest 3.5 and 3.4, and made the most of the simple changes suggested in http://bugs.python.org/review/11352/#ps4792 . I've also added all the non internal parameters to the FieldStorage constructor, and descriptions of them. Thanks, Matt ---------- nosy: +mutley89 Added file: http://bugs.python.org/file38026/cgi-doc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Changes by Ivan Levkivskyi <levkivskyi@gmail.com>: ---------- nosy: +levkivskyi _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________
Change by Mark Lawrence <breamoreboy@gmail.com>: ---------- nosy: -BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11352> _______________________________________
participants (14)
-
A.M. Kuchling -
Berker Peksag
-
Hynek Schlawack
-
Ivan Levkivskyi
-
Jim Jewett
-
Mark Lawrence
-
Matthew Atkinson
-
Peter Kleiweg
-
Pierre Quentel
-
R. David Murray
-
Roundup Robot
-
Senthil Kumaran
-
STINNER Victor
-
Éric Araujo