[Python-checkins] cpython (merge 3.3 -> default): Issue #19198: Improved cross-references in the cgi module documentation.

[serhiy.storchaka]

http://hg.python.org/cpython/rev/781deb421ad0
changeset:   86313:781deb421ad0
parent:      86309:eeed65cb68b0
parent:      86312:e52e259d42e8
user:        Serhiy Storchaka <storchaka at gmail.com>
date:        Sun Oct 13 18:29:08 2013 +0300
summary:
  Issue #19198: Improved cross-references in the cgi module documentation.

files:
  Doc/library/cgi.rst |  36 +++++++++++++++++---------------
  1 files changed, 19 insertions(+), 17 deletions(-)


diff --git a/Doc/library/cgi.rst b/Doc/library/cgi.rst
--- a/Doc/library/cgi.rst
+++ b/Doc/library/cgi.rst
@@ -97,7 +97,7 @@
 
 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 @@
 
 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 @@
 
 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 @@
 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)

-- 
Repository URL: http://hg.python.org/cpython