mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-10-03 13:45:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Issue #19198: Improved cross-references in the cgi module documentation.

Browse source
This commit is contained in:
Serhiy Storchaka 2013-10-13 18:29:08 +03:00
commit 221d943c5b
1 changed files with 19 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

36
Doc/library/cgi.rst
View file

@ -97,7 +97,7 @@ standard input, it should be instantiated only once.
The :class:`FieldStorage` instance can be indexed like a Python dictionary. The :class:`FieldStorage` instance can be indexed like a Python dictionary.
It allows membership testing with the :keyword:`in` operator, and also supports It allows membership testing with the :keyword:`in` operator, and also supports
the standard dictionary method :meth:`keys` and the built-in function the standard dictionary method :meth:`~dict.keys` and the built-in function
:func:`len`. Form fields containing empty strings are ignored and do not appear :func:`len`. Form fields containing empty strings are ignored and do not appear
in the dictionary; to keep such values, provide a true value for the optional in the dictionary; to keep such values, provide a true value for the optional
*keep_blank_values* keyword parameter when creating the :class:`FieldStorage` *keep_blank_values* keyword parameter when creating the :class:`FieldStorage`
@ -119,30 +119,32 @@ string::
Here the fields, accessed through ``form[key]``, are themselves instances of Here the fields, accessed through ``form[key]``, are themselves instances of
:class:`FieldStorage` (or :class:`MiniFieldStorage`, depending on the form :class:`FieldStorage` (or :class:`MiniFieldStorage`, depending on the form
encoding). The :attr:`value` attribute of the instance yields the string value encoding). The :attr:`~FieldStorage.value` attribute of the instance yields
of the field. The :meth:`getvalue` method returns this string value directly; the string value of the field. The :meth:`~FieldStorage.getvalue` method
it also accepts an optional second argument as a default to return if the returns this string value directly; it also accepts an optional second argument
requested key is not present. as a default to return if the requested key is not present.
If the submitted form data contains more than one field with the same name, the If the submitted form data contains more than one field with the same name, the
object retrieved by ``form[key]`` is not a :class:`FieldStorage` or object retrieved by ``form[key]`` is not a :class:`FieldStorage` or
:class:`MiniFieldStorage` instance but a list of such instances. Similarly, in :class:`MiniFieldStorage` instance but a list of such instances. Similarly, in
this situation, ``form.getvalue(key)`` would return a list of strings. If you this situation, ``form.getvalue(key)`` would return a list of strings. If you
expect this possibility (when your HTML form contains multiple fields with the expect this possibility (when your HTML form contains multiple fields with the
same name), use the :func:`getlist` function, which always returns a list of same name), use the :meth:`~FieldStorage.getlist` method, which always returns
values (so that you do not need to special-case the single item case). For a list of values (so that you do not need to special-case the single item
example, this code concatenates any number of username fields, separated by case). For example, this code concatenates any number of username fields,
commas:: separated by commas::
value = form.getlist("username") value = form.getlist("username")
usernames = ",".join(value) usernames = ",".join(value)
If a field represents an uploaded file, accessing the value via the If a field represents an uploaded file, accessing the value via the
:attr:`value` attribute or the :func:`getvalue` method reads the entire file in :attr:`~FieldStorage.value` attribute or the :meth:`~FieldStorage.getvalue`
memory as bytes. This may not be what you want. You can test for an uploaded method reads the entire file in memory as bytes. This may not be what you
file by testing either the :attr:`filename` attribute or the :attr:`!file` want. You can test for an uploaded file by testing either the
:attr:`~FieldStorage.filename` attribute or the :attr:`~FieldStorage.file`
attribute. You can then read the data at leisure from the :attr:`!file` attribute. You can then read the data at leisure from the :attr:`!file`
attribute (the :func:`read` and :func:`readline` methods will return bytes):: attribute (the :func:`~io.RawIOBase.read` and :func:`~io.IOBase.readline`
methods will return bytes)::
fileitem = form["userfile"] fileitem = form["userfile"]
if fileitem.file: if fileitem.file:
@ -155,8 +157,8 @@ attribute (the :func:`read` and :func:`readline` methods will return bytes)::
If an error is encountered when obtaining the contents of an uploaded file If an error is encountered when obtaining the contents of an uploaded file
(for example, when the user interrupts the form submission by clicking on (for example, when the user interrupts the form submission by clicking on
a Back or Cancel button) the :attr:`done` attribute of the object for the a Back or Cancel button) the :attr:`~FieldStorage.done` attribute of the
field will be set to the value -1. object for the field will be set to the value -1.
The file upload draft standard entertains the possibility of uploading multiple The file upload draft standard entertains the possibility of uploading multiple
files from one field (using a recursive :mimetype:`multipart/\*` encoding). files from one field (using a recursive :mimetype:`multipart/\*` encoding).
@ -223,8 +225,8 @@ Therefore, the appropriate way to read form data values was to always use the
code which checks whether the obtained value is a single value or a list of code which checks whether the obtained value is a single value or a list of
values. That's annoying and leads to less readable scripts. values. That's annoying and leads to less readable scripts.
A more convenient approach is to use the methods :meth:`getfirst` and A more convenient approach is to use the methods :meth:`~FieldStorage.getfirst`
:meth:`getlist` provided by this higher level interface. and :meth:`~FieldStorage.getlist` provided by this higher level interface.
.. method:: FieldStorage.getfirst(name, default=None) .. method:: FieldStorage.getfirst(name, default=None)