[Python-checkins] cpython (3.3): Improve #19204: Improved cross-references in the urllib package documentation.
serhiy.storchaka
python-checkins at python.org
Sun Oct 13 19:08:17 CEST 2013
http://hg.python.org/cpython/rev/3901ff1e6547
changeset: 86320:3901ff1e6547
branch: 3.3
parent: 86318:23b6f485e59c
user: Serhiy Storchaka <storchaka at gmail.com>
date: Sun Oct 13 20:06:50 2013 +0300
summary:
Improve #19204: Improved cross-references in the urllib package documentation.
files:
Doc/library/urllib.error.rst | 8 ++-
Doc/library/urllib.parse.rst | 4 +-
Doc/library/urllib.request.rst | 41 +++++++++++----------
Doc/library/urllib.rst | 2 +
4 files changed, 30 insertions(+), 25 deletions(-)
diff --git a/Doc/library/urllib.error.rst b/Doc/library/urllib.error.rst
--- a/Doc/library/urllib.error.rst
+++ b/Doc/library/urllib.error.rst
@@ -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
@@ -47,7 +48,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 --git a/Doc/library/urllib.parse.rst b/Doc/library/urllib.parse.rst
--- a/Doc/library/urllib.parse.rst
+++ b/Doc/library/urllib.parse.rst
@@ -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 --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
--- a/Doc/library/urllib.request.rst
+++ b/Doc/library/urllib.request.rst
@@ -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()
@@ -240,7 +240,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()
@@ -614,8 +614,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
@@ -674,8 +674,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.
@@ -761,8 +762,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,
@@ -775,9 +776,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::
@@ -979,7 +980,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.
.. _ftp-handler-objects:
@@ -1021,7 +1022,7 @@
.. method:: UnknownHandler.unknown_open()
- Raise a :exc:`URLError` exception.
+ Raise a :exc:`~urllib.error.URLError` exception.
.. _http-error-processor-objects:
@@ -1038,7 +1039,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()
@@ -1251,7 +1252,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
@@ -1333,8 +1334,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 --git a/Doc/library/urllib.rst b/Doc/library/urllib.rst
--- 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
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list