Skip to content

[3.6] bpo-35155: clarify protocol handler method naming (GH-10313) #12503

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
miss-islington wants to merge 1 commit into from
Closed

[3.6] bpo-35155: clarify protocol handler method naming (GH-10313) #12503

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 39 additions & 19 deletions Doc/library/urllib.request.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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])

Expand All @@ -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`.
Expand All @@ -653,25 +669,25 @@ 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`.

Note that the implementation of these methods may involve calls of the parent
: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.


Expand Down Expand Up @@ -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`.


Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand Down