`urllib.request.HTTPRedirectHandler` documentation uses `hdrs` instead of `headers`

[niooss-ledger]

Documentation

Hello, HTTPRedirectHandler documentation documents some methods take HTTP headers in a parameter named hdrs:

cpython/Doc/library/urllib.request.rst

Line 896 in c646846

.. method:: HTTPRedirectHandler.redirect_request(req, fp, code, msg, hdrs, newurl)

cpython/Doc/library/urllib.request.rst

Line 915 in c646846

.. method:: HTTPRedirectHandler.http_error_301(req, fp, code, msg, hdrs)

cpython/Doc/library/urllib.request.rst

Line 921 in c646846

.. method:: HTTPRedirectHandler.http_error_302(req, fp, code, msg, hdrs)

...

However, the actual implementation uses headers:

cpython/Lib/urllib/request.py

Line 621 in c646846

def redirect_request(self, req, fp, code, msg, headers, newurl):

cpython/Lib/urllib/request.py

Line 660 in c646846

def http_error_302(self, req, fp, code, msg, headers):

Would it be possible to use the same name in the documentation and in the implementation?

Context

In some project, the following class is used to perform HTTPS requests without following redirection:

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(
        self, req: Any, fp: Any, code: Any, msg: Any, hdrs: Any, newurl: Any
    ) -> None:
        pass

Running a type checker (basedpyright) on this code reports a warning:

error: Method "redirect_request" overrides class "HTTPRedirectHandler" in an incompatible manner
  Parameter 6 name mismatch: base parameter is named "headers",
  override parameter is named "hdrs" (reportIncompatibleMethodOverride)

This was quite unexpected because the official documentation (https://docs.python.org/3.13/library/urllib.request.html#urllib.request.HTTPRedirectHandler.redirect_request) mentions hdrs instead of headers. It makes nonetheless more sense to name the parameter headers in case callers use the parameter names.

Linked PRs

• gh-135468: Improve BaseHandler.http_error_default() parameter descriptions #136797
• [3.14] gh-135468: Improve BaseHandler.http_error_default() parameter descriptions (GH-136797) #136825
• [3.13] gh-135468: Improve BaseHandler.http_error_default() parameter descriptions (GH-136797) #136826

[terryjreedy]

Yes, doc errors should be fixed, including all 5 error functions (which by default all refer to the same function). (Error is a puzzle since 'blame' says signature unchanged since original 17 years ago.) I will do it.

[terryjreedy]

There are 4 other methods with the same mismatch to be fixed (in my branch 'headers') and backported.

I wonder about changing hdrs to headers (3 places) in these descriptions of user-written methods.

cpython/Doc/library/urllib.request.rst

Lines 825 to 852 in c646846

	.. method:: BaseHandler.http_error_default(req, fp, code, msg, hdrs)
	This method is *not* defined in :class:`BaseHandler`, but subclasses should
	override it if they intend to provide a catch-all for otherwise unhandled HTTP
	errors. It will be called automatically by the :class:`OpenerDirector` getting
	the error, and should not normally be called in other circumstances.
	*req* will be a :class:`Request` object, *fp* will be a file-like object with
	the HTTP error body, *code* will be the three-digit code of the error, *msg*
	will be the user-visible explanation of the code and *hdrs* will be a mapping
	object with the headers of the error.
	Return values and exceptions raised should be the same as those of
	:func:`urlopen`.
	.. _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
	subclass, when an HTTP error with code *nnn* occurs.
	Subclasses should override this method to handle specific HTTP errors.
	Arguments, return values and exceptions raised should be the same as for
	:meth:`~BaseHandler.http_error_default`.

It seems these should be changed for consistency, but I wonder if there are any back-compatibility concerns, especially for
backports. @encukou what do you think?

[encukou]

For a user-written function, there'd be backcompat concerns if a library defines one and another calls/extends that.
Perhaps the docs would be both clearer and more explicit like this:

    [...] It will be called automatically by the  :class:`OpenerDirector` getting 
    the error, and should not normally be called in other circumstances.

    :class:`OpenerDirector` will call this method with five positional arguments:
  
    - a :class:`Request` object,
    - a file-like object with the HTTP error body,
    - the three-digit code of the error, as a string,
    - the user-visible explanation of the code, as as string, and
    - the headers of the error, as a mapping object.

[vgiane]

I will try to clarify the paragraph. Working on this from EP 2025 Sprints.