[Python-checkins] r68117 - python/trunk/Doc/library/urllib2.rst
georg.brandl
python-checkins at python.org
Thu Jan 1 12:53:56 CET 2009
Author: georg.brandl
Date: Thu Jan 1 12:53:55 2009
New Revision: 68117
Log:
#4156: make clear that "protocol" is to be replaced with the protocol name.
Modified:
python/trunk/Doc/library/urllib2.rst
Modified: python/trunk/Doc/library/urllib2.rst
==============================================================================
--- python/trunk/Doc/library/urllib2.rst (original)
+++ python/trunk/Doc/library/urllib2.rst Thu Jan 1 12:53:55 2009
@@ -391,23 +391,23 @@
.. method:: OpenerDirector.add_handler(handler)
- *handler* should be an instance of :class:`BaseHandler`. The following methods
- are searched, and added to the possible chains (note that HTTP errors are a
- special case).
+ *handler* should be an instance of :class:`BaseHandler`. The following
+ methods are searched, and added to the possible chains (note that HTTP errors
+ are a special case).
- * :meth:`protocol_open` --- signal that the handler knows how to open *protocol*
- URLs.
+ * :samp:`{protocol}_open` --- signal that the handler knows how to open
+ *protocol* URLs.
- * :meth:`http_error_type` --- signal that the handler knows how to handle HTTP
- errors with HTTP error code *type*.
+ * :samp:`http_error_{type}` --- signal that the handler knows how to handle
+ HTTP errors with HTTP error code *type*.
- * :meth:`protocol_error` --- signal that the handler knows how to handle errors
- from (non-\ ``http``) *protocol*.
+ * :samp:`{protocol}_error` --- signal that the handler knows how to handle
+ errors from (non-\ ``http``) *protocol*.
- * :meth:`protocol_request` --- signal that the handler knows how to pre-process
- *protocol* requests.
+ * :samp:`{protocol}_request` --- signal that the handler knows how to
+ pre-process *protocol* requests.
- * :meth:`protocol_response` --- signal that the handler knows how to
+ * :samp:`{protocol}_response` --- signal that the handler knows how to
post-process *protocol* responses.
@@ -441,24 +441,24 @@
The order in which these methods are called within each stage is determined by
sorting the handler instances.
-#. Every handler with a method named like :meth:`protocol_request` has that
+#. Every handler with a method named like :samp:`{protocol}_request` has that
method called to pre-process the request.
-#. Handlers with a method named like :meth:`protocol_open` are called to handle
+#. Handlers with a method named like :samp:`{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.
In fact, the above algorithm is first tried for methods named
- :meth:`default_open`. If all such methods return :const:`None`, the algorithm
- is repeated for methods named like :meth:`protocol_open`. If all such methods
- return :const:`None`, the algorithm is repeated for methods named
- :meth:`unknown_open`.
+ :meth:`default_open`. If all such methods return :const:`None`, the
+ algorithm is repeated for methods named like :samp:`{protocol}_open`. If all
+ such methods return :const:`None`, the algorithm is repeated for methods
+ named :meth:`unknown_open`.
Note that the implementation of these methods may involve calls of the parent
:class:`OpenerDirector` instance's :meth:`.open` and :meth:`.error` methods.
-#. Every handler with a method named like :meth:`protocol_response` has that
+#. Every handler with a method named like :samp:`{protocol}_response` has that
method called to post-process the response.
@@ -514,8 +514,10 @@
.. method:: BaseHandler.protocol_open(req)
:noindex:
+ ("protocol" is to be replaced by the protocol name.)
+
This method is *not* defined in :class:`BaseHandler`, but subclasses should
- define it if they want to handle URLs with the given protocol.
+ define it if they want to handle URLs with the given *protocol*.
This method, if defined, will be called by the parent :class:`OpenerDirector`.
Return values should be the same as for :meth:`default_open`.
@@ -563,8 +565,10 @@
.. method:: BaseHandler.protocol_request(req)
:noindex:
+ ("protocol" is to be replaced by the protocol name.)
+
This method is *not* defined in :class:`BaseHandler`, but subclasses should
- define it if they want to pre-process requests of the given protocol.
+ define it if they want to pre-process requests of the given *protocol*.
This method, if defined, will be called by the parent :class:`OpenerDirector`.
*req* will be a :class:`Request` object. The return value should be a
@@ -574,8 +578,10 @@
.. method:: BaseHandler.protocol_response(req, response)
:noindex:
+ ("protocol" is to be replaced by the protocol name.)
+
This method is *not* defined in :class:`BaseHandler`, but subclasses should
- define it if they want to post-process responses of the given protocol.
+ define it if they want to post-process responses of the given *protocol*.
This method, if defined, will be called by the parent :class:`OpenerDirector`.
*req* will be a :class:`Request` object. *response* will be an object
@@ -660,7 +666,9 @@
.. method:: ProxyHandler.protocol_open(request)
:noindex:
- The :class:`ProxyHandler` will have a method :meth:`protocol_open` for every
+ ("protocol" is to be replaced by the protocol name.)
+
+ The :class:`ProxyHandler` will have a method :samp:`{protocol}_open` for every
*protocol* which has a proxy in the *proxies* dictionary given in the
constructor. The method will modify requests to go through the proxy, by
calling ``request.set_proxy()``, and call the next handler in the chain to
@@ -865,9 +873,10 @@
For 200 error codes, the response object is returned immediately.
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:`urllib2.HTTPDefaultErrorHandler` will raise an
- :exc:`HTTPError` if no other handler handles the error.
+ :samp:`{protocol}_error_code` handler methods, via
+ :meth:`OpenerDirector.error`. Eventually,
+ :class:`urllib2.HTTPDefaultErrorHandler` will raise an :exc:`HTTPError` if no
+ other handler handles the error.
.. _urllib2-examples:
More information about the Python-checkins
mailing list