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

1 files changed, 39 insertions, 19 deletions

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 @@ OpenerDirector Objects
 
    *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 @@ OpenerDirector Objects
    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 @@ OpenerDirector objects open URLs in three stages:
 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 @@ sorting the handler instances.
    :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 @@ The following attribute and methods should only be used by classes derived from
 .. 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 @@ The following attribute and methods should only be used by classes derived from
    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 @@ The following attribute and methods should only be used by classes derived from
    :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 @@ The following attribute and methods should only be used by classes derived from
    :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 @@ The following attribute and methods should only be used by classes derived from
    :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 @@ ProxyHandler Objects
 --------------------
 
 
-.. 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 @@ HTTPErrorProcessor Objects
    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.