diff -r d76e91a29f64 Doc/library/urllib.error.rst --- a/Doc/library/urllib.error.rst Wed Oct 09 14:20:37 2013 +0300 +++ b/Doc/library/urllib.error.rst Wed Oct 09 15:25:29 2013 +0300 @@ -31,8 +31,9 @@ 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 @@ .. 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 -r d76e91a29f64 Doc/library/urllib.parse.rst --- a/Doc/library/urllib.parse.rst Wed Oct 09 14:20:37 2013 +0300 +++ b/Doc/library/urllib.parse.rst Wed Oct 09 15:25:29 2013 +0300 @@ -518,8 +518,8 @@ 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 -r d76e91a29f64 Doc/library/urllib.request.rst --- a/Doc/library/urllib.request.rst Wed Oct 09 14:20:37 2013 +0300 +++ b/Doc/library/urllib.request.rst Wed Oct 09 15:25:29 2013 +0300 @@ -81,7 +81,7 @@ * :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 @@ 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 @@ .. 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 @@ #. 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 @@ 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 @@ .. 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 @@ 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 @@ .. 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 @@ .. method:: UnknownHandler.unknown_open() - Raise a :exc:`URLError` exception. + Raise a :exc:`~urllib.error.URLError` exception. .. _http-error-processor-objects: @@ -1021,7 +1022,7 @@ 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 @@ 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 @@ 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 -r d76e91a29f64 Doc/library/urllib.rst --- a/Doc/library/urllib.rst Wed Oct 09 14:20:37 2013 +0300 +++ b/Doc/library/urllib.rst Wed Oct 09 15:25:29 2013 +0300 @@ -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