bpo-35155: clarify protocol handler method naming (GH-10313)
Clarify that the naming of protocol handler methods shouldn't be literally called "protocol" but should be named after the actual protocol.
https://bugs.python.org/issue35155
(cherry picked from commit dd7c4ceed90792f711347024852d4cf883a9ab9e)
Co-authored-by: Denton Liu <liu.denton+github@gmail.com>
diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
index 982f57f..289bfca 100644
--- a/Doc/library/urllib.request.rst
+++ b/Doc/library/urllib.request.rst
@@ -608,23 +608,39 @@
*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).
+ special case). Note that, in the following, *protocol* should be replaced
+ with the actual protocol to handle, for example :meth:`http_response` would
+ be the HTTP protocol response handler. Also *type* should be replaced with
+ the actual HTTP code, for example :meth:`http_error_404` would handle HTTP
+ 404 errors.
- * :meth:`protocol_open` --- signal that the handler knows how to open *protocol*
+ * :meth:`<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
+ See |protocol_open|_ for more information.
+
+ * :meth:`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
+ See |http_error_nnn|_ for more information.
+
+ * :meth:`<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
+ * :meth:`<protocol>_request` --- signal that the handler knows how to pre-process
*protocol* requests.
- * :meth:`protocol_response` --- signal that the handler knows how to
+ See |protocol_request|_ for more information.
+
+ * :meth:`<protocol>_response` --- signal that the handler knows how to
post-process *protocol* responses.
+ See |protocol_response|_ for more information.
+
+.. |protocol_open| replace:: :meth:`BaseHandler.<protocol>_open`
+.. |http_error_nnn| replace:: :meth:`BaseHandler.http_error_\<nnn\>`
+.. |protocol_request| replace:: :meth:`BaseHandler.<protocol>_request`
+.. |protocol_response| replace:: :meth:`BaseHandler.<protocol>_response`
.. method:: OpenerDirector.open(url, data=None[, timeout])
@@ -643,7 +659,7 @@
Handle an error of the given protocol. This will call the registered error
handlers for the given protocol with the given arguments (which are protocol
specific). The HTTP protocol is a special case which uses the HTTP response
- code to determine the specific error handler; refer to the :meth:`http_error_\*`
+ code to determine the specific error handler; refer to the :meth:`http_error_\<type\>`
methods of the handler classes.
Return values and exceptions raised are the same as those of :func:`urlopen`.
@@ -653,17 +669,17 @@
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 :meth:`<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 :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:`~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
- is repeated for methods named like :meth:`protocol_open`. If all such methods
+ 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`.
@@ -671,7 +687,7 @@
:class:`OpenerDirector` instance's :meth:`~OpenerDirector.open` and
:meth:`~OpenerDirector.error` methods.
-#. Every handler with a method named like :meth:`protocol_response` has that
+#. Every handler with a method named like :meth:`<protocol>_response` has that
method called to post-process the response.
@@ -700,7 +716,7 @@
.. note::
The convention has been adopted that subclasses defining
- :meth:`protocol_request` or :meth:`protocol_response` methods are named
+ :meth:`<protocol>_request` or :meth:`<protocol>_response` methods are named
:class:`\*Processor`; all others are named :class:`\*Handler`.
@@ -725,7 +741,8 @@
This method will be called before any protocol-specific open method.
-.. method:: BaseHandler.protocol_open(req)
+.. _protocol_open:
+.. method:: BaseHandler.<protocol>_open(req)
:noindex:
This method is *not* defined in :class:`BaseHandler`, but subclasses should
@@ -762,7 +779,8 @@
:func:`urlopen`.
-.. method:: BaseHandler.http_error_nnn(req, fp, code, msg, hdrs)
+.. _http_error_nnn:
+.. method:: BaseHandler.http_error_<nnn>(req, fp, code, msg, hdrs)
*nnn* should be a three-digit HTTP error code. This method is also not defined
in :class:`BaseHandler`, but will be called, if it exists, on an instance of a
@@ -774,7 +792,8 @@
:meth:`http_error_default`.
-.. method:: BaseHandler.protocol_request(req)
+.. _protocol_request:
+.. method:: BaseHandler.<protocol>_request(req)
:noindex:
This method is *not* defined in :class:`BaseHandler`, but subclasses should
@@ -785,7 +804,8 @@
:class:`Request` object.
-.. method:: BaseHandler.protocol_response(req, response)
+.. _protocol_response:
+.. method:: BaseHandler.<protocol>_response(req, response)
:noindex:
This method is *not* defined in :class:`BaseHandler`, but subclasses should
@@ -873,10 +893,10 @@
--------------------
-.. method:: ProxyHandler.protocol_open(request)
+.. method:: ProxyHandler.<protocol>_open(request)
:noindex:
- The :class:`ProxyHandler` will have a method :meth:`protocol_open` for every
+ The :class:`ProxyHandler` will have a method :meth:`<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
@@ -1132,7 +1152,7 @@
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`.
+ :meth:`http_error_\<type\>` handler methods, via :meth:`OpenerDirector.error`.
Eventually, :class:`HTTPDefaultErrorHandler` will raise an
:exc:`~urllib.error.HTTPError` if no other handler handles the error.