cpython: 781deb421ad0 (original) (raw)

Mercurial > cpython

changeset 86313:781deb421ad0

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

line wrap: on

line diff

--- a/Doc/library/cgi.rst +++ b/Doc/library/cgi.rst @@ -97,7 +97,7 @@ standard input, it should be instantiate 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:r[](#l1.57) [](#l1.58) If an error is encountered when obtaining the contents of an uploaded file[](#l1.59) (for example, when the user interrupts the form submission by clicking on[](#l1.60) -a Back or Cancel button) the :attr:done attribute of the object for the[](#l1.61) -field will be set to the value -1.[](#l1.62) +a Back or Cancel button) the :attr:FieldStorage.done attribute of the[](#l1.63) +object for the field will be set to the value -1.[](#l1.64) [](#l1.65) The file upload draft standard entertains the possibility of uploading multiple[](#l1.66) files from one field (using a recursive :mimetype:multipart/* encoding).[](#l1.67) @@ -223,8 +225,8 @@ Therefore, the appropriate way to read f[](#l1.68) code which checks whether the obtained value is a single value or a list of[](#l1.69) values. That's annoying and leads to less readable scripts.[](#l1.70) [](#l1.71) -A more convenient approach is to use the methods :meth:getfirst and[](#l1.72) -:meth:getlist provided by this higher level interface.[](#l1.73) +A more convenient approach is to use the methods :meth:FieldStorage.getfirst[](#l1.74) +and :meth:~FieldStorage.getlist` provided by this higher level interface. .. method:: FieldStorage.getfirst(name, default=None)