diff options
Diffstat (limited to 'Doc/library/cgi.rst')
| -rw-r--r-- | Doc/library/cgi.rst | 36 |
1 files changed, 19 insertions, 17 deletions
diff --git a/Doc/library/cgi.rst b/Doc/library/cgi.rst index 478c95a9b0..c4e7c60539 100644 --- a/Doc/library/cgi.rst +++ b/Doc/library/cgi.rst @@ -97,7 +97,7 @@ standard input, it should be instantiated only once. The :class:`FieldStorage` instance can be indexed like a Python dictionary. 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 in the dictionary; to keep such values, provide a true value for the optional *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 :class:`FieldStorage` (or :class:`MiniFieldStorage`, depending on the form -encoding). The :attr:`value` attribute of the instance yields the string value -of the field. The :meth:`getvalue` method returns this string value directly; -it also accepts an optional second argument as a default to return if the -requested key is not present. +encoding). The :attr:`~FieldStorage.value` attribute of the instance yields +the string value of the field. The :meth:`~FieldStorage.getvalue` method +returns this string value directly; it also accepts an optional second argument +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 object retrieved by ``form[key]`` is not a :class:`FieldStorage` or :class:`MiniFieldStorage` instance but a list of such instances. Similarly, in 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 -same name), use the :func:`getlist` function, which always returns a list of -values (so that you do not need to special-case the single item case). For -example, this code concatenates any number of username fields, separated by -commas:: +same name), use the :meth:`~FieldStorage.getlist` method, which always returns +a list of values (so that you do not need to special-case the single item +case). For example, this code concatenates any number of username fields, +separated by commas:: value = form.getlist("username") usernames = ",".join(value) 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 -memory as bytes. This may not be what you want. You can test for an uploaded -file by testing either the :attr:`filename` attribute or the :attr:`!file` +:attr:`~FieldStorage.value` attribute or the :meth:`~FieldStorage.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 +:attr:`~FieldStorage.filename` attribute or the :attr:`~FieldStorage.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"] 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 (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 -field will be set to the value -1. +a Back or Cancel button) the :attr:`~FieldStorage.done` attribute of the +object for the field will be set to the value -1. The file upload draft standard entertains the possibility of uploading multiple 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 values. That's annoying and leads to less readable scripts. -A more convenient approach is to use the methods :meth:`getfirst` and -:meth:`getlist` provided by this higher level interface. +A more convenient approach is to use the methods :meth:`~FieldStorage.getfirst` +and :meth:`~FieldStorage.getlist` provided by this higher level interface. .. method:: FieldStorage.getfirst(name, default=None) |