Improve #19204: Improved cross-references in the urllib package documentation.

serhiy-storchaka · serhiy-storchaka · commit 10e73babad7c · 2013-10-13T20:07:51.000+03:00
diff --git a/Doc/library/urllib.error.rst b/Doc/library/urllib.error.rst
@@ -31,8 +31,9 @@ The following exceptions are raised by :mod:`urllib.error` as appropriate:
 
    Though being an exception (a subclass of :exc:`URLError`), an
    :exc:`HTTPError` can also function as a non-exceptional file-like return
-   value (the same thing that :func:`urlopen` returns).  This is useful when
-   handling exotic HTTP errors, such as requests for authentication.
+   value (the same thing that :func:`~urllib.request.urlopen` returns).  This
+   is useful when handling exotic HTTP errors, such as requests for
+   authentication.
 
    .. attribute:: code
 
@@ -54,7 +55,8 @@ The following exceptions are raised by :mod:`urllib.error` as appropriate:
 
 .. exception:: ContentTooShortError(msg, content)
 
-   This exception is raised when the :func:`urlretrieve` function detects that
+   This exception is raised when the :func:`~urllib.request.urlretrieve`
+   function detects that
    the amount of the downloaded data is less than the expected amount (given by
    the *Content-Length* header).  The :attr:`content` attribute stores the
    downloaded (and supposedly truncated) data.
diff --git a/Doc/library/urllib.parse.rst b/Doc/library/urllib.parse.rst
@@ -518,8 +518,8 @@ task isn't already covered by the URL parsing functions above.
    Convert a mapping object or a sequence of two-element tuples, which may
    either be a :class:`str` or a :class:`bytes`,  to a "percent-encoded"
    string.  If the resultant string is to be used as a *data* for POST
-   operation with :func:`urlopen` function, then it should be properly encoded
-   to bytes, otherwise it would result in a :exc:`TypeError`.
+   operation with :func:`~urllib.request.urlopen` function, then it should be
+   properly encoded to bytes, otherwise it would result in a :exc:`TypeError`.
 
    The resulting string is a series of ``key=value`` pairs separated by ``'&'``
    characters, where both *key* and *value* are quoted using :func:`quote_plus`
diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
@@ -81,7 +81,7 @@ The :mod:`urllib.request` module defines the following functions:
 
    * :meth:`~urllib.response.addinfourl.getcode` -- return the HTTP status code of the response.
 
-   Raises :exc:`URLError` on errors.
+   Raises :exc:`~urllib.error.URLError` on errors.
 
    Note that ``None`` may be returned if no handler handles the request (though
    the default installed global :class:`OpenerDirector` uses
@@ -144,14 +144,14 @@ The :mod:`urllib.request` module defines the following functions:
 
    Convert the pathname *path* from the local syntax for a path to the form used in
    the path component of a URL.  This does not produce a complete URL.  The return
-   value will already be quoted using the :func:`quote` function.
+   value will already be quoted using the :func:`~urllib.parse.quote` function.
 
 
 .. function:: url2pathname(path)
 
    Convert the path component *path* from a percent-encoded URL to the local syntax for a
-   path.  This does not accept a complete URL.  This function uses :func:`unquote`
-   to decode *path*.
+   path.  This does not accept a complete URL.  This function uses
+   :func:`~urllib.parse.unquote` to decode *path*.
 
 .. function:: getproxies()
 
@@ -245,7 +245,7 @@ The following classes are provided:
 .. class:: HTTPDefaultErrorHandler()
 
    A class which defines a default handler for HTTP error responses; all responses
-   are turned into :exc:`HTTPError` exceptions.
+   are turned into :exc:`~urllib.error.HTTPError` exceptions.
 
 
 .. class:: HTTPRedirectHandler()
@@ -582,8 +582,8 @@ sorting the handler instances.
 
 #. Handlers with a method named like :meth:`protocol_open` are called to handle
    the request. This stage ends when a handler either returns a non-\ :const:`None`
-   value (ie. a response), or raises an exception (usually :exc:`URLError`).
-   Exceptions are allowed to propagate.
+   value (ie. a response), or raises an exception (usually
+   :exc:`~urllib.error.URLError`).  Exceptions are allowed to propagate.
 
    In fact, the above algorithm is first tried for methods named
    :meth:`default_open`.  If all such methods return :const:`None`, the algorithm
@@ -642,8 +642,9 @@ The following attribute and methods should only be used by classes derived from
    This method, if implemented, will be called by the parent
    :class:`OpenerDirector`.  It should return a file-like object as described in
    the return value of the :meth:`open` of :class:`OpenerDirector`, or ``None``.
-   It should raise :exc:`URLError`, unless a truly exceptional thing happens (for
-   example, :exc:`MemoryError` should not be mapped to :exc:`URLError`).
+   It should raise :exc:`~urllib.error.URLError`, unless a truly exceptional
+   thing happens (for example, :exc:`MemoryError` should not be mapped to
+   :exc:`URLError`).
 
    This method will be called before any protocol-specific open method.
 
@@ -729,8 +730,8 @@ HTTPRedirectHandler Objects
 .. note::
 
    Some HTTP redirections require action from this module's client code.  If this
-   is the case, :exc:`HTTPError` is raised.  See :rfc:`2616` for details of the
-   precise meanings of the various redirection codes.
+   is the case, :exc:`~urllib.error.HTTPError` is raised.  See :rfc:`2616` for
+   details of the precise meanings of the various redirection codes.
 
    An :class:`HTTPError` exception raised as a security consideration if the
    HTTPRedirectHandler is presented with a redirected url which is not an HTTP,
@@ -743,9 +744,9 @@ HTTPRedirectHandler Objects
    by the default implementations of the :meth:`http_error_30\*` methods when a
    redirection is received from the server.  If a redirection should take place,
    return a new :class:`Request` to allow :meth:`http_error_30\*` to perform the
-   redirect to *newurl*.  Otherwise, raise :exc:`HTTPError` if no other handler
-   should try to handle this URL, or return ``None`` if you can't but another
-   handler might.
+   redirect to *newurl*.  Otherwise, raise :exc:`~urllib.error.HTTPError` if
+   no other handler should try to handle this URL, or return ``None`` if you
+   can't but another handler might.
 
    .. note::
 
@@ -947,7 +948,7 @@ FileHandler Objects
 
    .. versionchanged:: 3.2
       This method is applicable only for local hostnames.  When a remote
-      hostname is given, an :exc:`URLError` is raised.
+      hostname is given, an :exc:`~urllib.error.URLError` is raised.
 
 
 .. _data-handler-objects:
@@ -1004,7 +1005,7 @@ UnknownHandler Objects
 
 .. method:: UnknownHandler.unknown_open()
 
-   Raise a :exc:`URLError` exception.
+   Raise a :exc:`~urllib.error.URLError` exception.
 
 
 .. _http-error-processor-objects:
@@ -1021,7 +1022,7 @@ HTTPErrorProcessor Objects
    For non-200 error codes, this simply passes the job on to the
    :meth:`protocol_error_code` handler methods, via :meth:`OpenerDirector.error`.
    Eventually, :class:`HTTPDefaultErrorHandler` will raise an
-   :exc:`HTTPError` if no other handler handles the error.
+   :exc:`~urllib.error.HTTPError` if no other handler handles the error.
 
 
 .. method:: HTTPErrorProcessor.https_response()
@@ -1234,7 +1235,7 @@ some point in the future.
    argument may be given to specify a ``POST`` request (normally the request
    type is ``GET``).  The *data* argument must be a bytes object in standard
    :mimetype:`application/x-www-form-urlencoded` format; see the
-   :func:`urlencode` function below.
+   :func:`urllib.parse.urlencode` function.
 
    :func:`urlretrieve` will raise :exc:`ContentTooShortError` when it detects that
    the amount of data available  was less than the expected amount (which is the
@@ -1316,8 +1317,8 @@ some point in the future.
        If the *url* uses the :file:`http:` scheme identifier, the optional *data*
        argument may be given to specify a ``POST`` request (normally the request type
        is ``GET``).  The *data* argument must in standard
-       :mimetype:`application/x-www-form-urlencoded` format; see the :func:`urlencode`
-       function below.
+       :mimetype:`application/x-www-form-urlencoded` format; see the
+       :func:`urllib.parse.urlencode` function.
 
 
     .. attribute:: version
diff --git a/Doc/library/urllib.rst b/Doc/library/urllib.rst
@@ -1,6 +1,8 @@
 :mod:`urllib` --- URL handling modules
 ======================================
 
+.. module:: urllib
+
 ``urllib`` is a package that collects several modules for working with URLs:
 
 * :mod:`urllib.request` for opening and reading URLs
