From cc3a00937aeffecc41ab351cbd758526477560be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?= <10796600+picnixz@users.noreply.github.com> Date: Sun, 5 Jul 2026 10:18:39 +0200 Subject: [PATCH 01/10] gh-151945: fix warnings in `http.server` docs --- Doc/library/http.server.rst | 44 ++++++++++++++++++++++++++++++++++++- Doc/tools/.nitignore | 1 - 2 files changed, 43 insertions(+), 2 deletions(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index c4b9173f9e34eb2..5b9f1c599ad19dc 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -39,7 +39,17 @@ handler. Code to create and run the server looks like this:: This class builds on the :class:`~socketserver.TCPServer` class by storing the server address as instance variables named :attr:`server_name` and :attr:`server_port`. The server is accessible by the handler, typically - through the handler's :attr:`server` instance variable. + through the handler's :attr:`~socketserver.BaseRequestHandler.server` + instance variable. + + .. attribute:: server_name + + The HTTP server's fully qualified domain name. + + .. attribute:: server_port + + The HTTP server's port number obtained from *server_address*. + .. class:: ThreadingHTTPServer(server_address, RequestHandlerClass) @@ -402,6 +412,14 @@ instantiation, of which this module provides three different variants: .. versionadded:: 3.15 + .. attribute:: index_pages + + Specifies the filenames that are treated as directory index pages. + + Defaults to ``("index.html", "index.htm")``. + + .. versionadded:: 3.12 + .. attribute:: extensions_map A dictionary mapping suffixes into MIME types, contains custom overrides @@ -465,6 +483,30 @@ instantiation, of which this module provides three different variants: .. versionchanged:: 3.7 Support of the ``'If-Modified-Since'`` header. + The :class:`SimpleHTTPRequestHandler` class defines the following helpers: + + .. method:: list_directory() + + Helper to produce a directory listing (absent index.html). + + This returns either a :ref:`file-like ` object (which + must be closed by the caller) or ``None`` to indicate an error, in which + case the caller has nothing further to do. In either case, the headers + are sent. + + .. method:: guess_type(path) + + Guess the type of the file of given *path*. + + This returns a string of the form ``type/subtype``, usable for + a MIME Content-type header. + + The default implementation looks the file's extension up in + :attr:`extensions_map`, using ``"application/octet-stream"`` + as a default. + + + The :class:`SimpleHTTPRequestHandler` class can be used in the following manner in order to create a very basic webserver serving files relative to the current directory:: diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 2255c745c003838..9024519747457a5 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -10,7 +10,6 @@ Doc/library/asyncio-extending.rst Doc/library/email.charset.rst Doc/library/email.parser.rst Doc/library/http.cookiejar.rst -Doc/library/http.server.rst Doc/library/importlib.rst Doc/library/logging.config.rst Doc/library/logging.handlers.rst From bfa41d2e7585f3b930b650b3836110a606ca3441 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?= <10796600+picnixz@users.noreply.github.com> Date: Sun, 5 Jul 2026 10:32:41 +0200 Subject: [PATCH 02/10] Update Doc/library/http.server.rst Co-authored-by: Stan Ulbrych --- Doc/library/http.server.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index 5b9f1c599ad19dc..87f483f4f8cfa64 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -489,7 +489,7 @@ instantiation, of which this module provides three different variants: Helper to produce a directory listing (absent index.html). - This returns either a :ref:`file-like ` object (which + This returns either a :term:`file-like object` (which must be closed by the caller) or ``None`` to indicate an error, in which case the caller has nothing further to do. In either case, the headers are sent. From 0d74d4038b85526f09f0848597382d0f58e45a40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?= <10796600+picnixz@users.noreply.github.com> Date: Sun, 5 Jul 2026 10:33:42 +0200 Subject: [PATCH 03/10] fix `index_pages` ref --- Doc/library/http.server.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index 87f483f4f8cfa64..c60819794d1a17c 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -525,7 +525,7 @@ the current directory:: :class:`SimpleHTTPRequestHandler` can also be subclassed to enhance behavior, such as using different index file names by overriding the class attribute -:attr:`index_pages`. +:attr:`~SimpleHTTPRequestHandler.index_pages`. .. _http-server-cli: From 051352ee63cb1e576ab1ec60f10a2e07c2987c25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?= <10796600+picnixz@users.noreply.github.com> Date: Sun, 5 Jul 2026 10:41:13 +0200 Subject: [PATCH 04/10] update list_directory(path) --- Doc/library/http.server.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index c60819794d1a17c..4416e6dba837795 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -485,14 +485,13 @@ instantiation, of which this module provides three different variants: The :class:`SimpleHTTPRequestHandler` class defines the following helpers: - .. method:: list_directory() + .. method:: list_directory(path) - Helper to produce a directory listing (absent index.html). + Helper to list the contents of *path* when no index page is present. - This returns either a :term:`file-like object` (which - must be closed by the caller) or ``None`` to indicate an error, in which - case the caller has nothing further to do. In either case, the headers - are sent. + This returns either a :term:`file-like object` (which must be closed + by the caller) or ``None`` to indicate an error, in which case the + caller has nothing further to do. In either case, the headers are sent. .. method:: guess_type(path) From 9a00d7602a31c8ed9af5102b6d668f8b5dfd52a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?= <10796600+picnixz@users.noreply.github.com> Date: Sun, 5 Jul 2026 10:41:26 +0200 Subject: [PATCH 05/10] use at most 2 blank lines --- Doc/library/http.server.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index 4416e6dba837795..0c7da3701d46a6b 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -505,7 +505,6 @@ instantiation, of which this module provides three different variants: as a default. - The :class:`SimpleHTTPRequestHandler` class can be used in the following manner in order to create a very basic webserver serving files relative to the current directory:: From 74ab33a43655cf99785fe60f6fc432c0a8b7544d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?= <10796600+picnixz@users.noreply.github.com> Date: Sun, 5 Jul 2026 10:45:08 +0200 Subject: [PATCH 06/10] fix `guess_type` details --- Doc/library/http.server.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index 0c7da3701d46a6b..04d6100bc836618 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -501,8 +501,11 @@ instantiation, of which this module provides three different variants: a MIME Content-type header. The default implementation looks the file's extension up in - :attr:`extensions_map`, using ``"application/octet-stream"`` - as a default. + :attr:`extensions_map` and :func:`mimetypes.guess_file_type`, + using :attr:`default_content_type` as defaults. + + .. versionchanged:: 3.13 + Add :func:`mimetypes.guess_file_type` as a fallback. The :class:`SimpleHTTPRequestHandler` class can be used in the following From 4d346620acf42084f9ff95f458adac621b825cd0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?= <10796600+picnixz@users.noreply.github.com> Date: Sun, 5 Jul 2026 10:56:21 +0200 Subject: [PATCH 07/10] Update Doc/library/http.server.rst Co-authored-by: Stan Ulbrych --- Doc/library/http.server.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index 04d6100bc836618..a93194ced559b99 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -501,8 +501,9 @@ instantiation, of which this module provides three different variants: a MIME Content-type header. The default implementation looks the file's extension up in - :attr:`extensions_map` and :func:`mimetypes.guess_file_type`, - using :attr:`default_content_type` as defaults. + :attr:`extensions_map`, falling back to + :func:`mimetypes.guess_file_type` and then to + :attr:`default_content_type`. .. versionchanged:: 3.13 Add :func:`mimetypes.guess_file_type` as a fallback. From 370d2656ee9af8ef8ba4406f11d76de4dbe73b18 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?= <10796600+picnixz@users.noreply.github.com> Date: Sun, 5 Jul 2026 10:58:51 +0200 Subject: [PATCH 08/10] remove method separation --- Doc/library/http.server.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index a93194ced559b99..b92651b1fdcd181 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -453,7 +453,7 @@ instantiation, of which this module provides three different variants: path relative to the current working directory. If the request was mapped to a directory, the directory is checked for a - file named ``index.html`` or ``index.htm`` (in that order). If found, the + an index page as specified by :attr:`index_pages`. If found, the file's contents are returned; otherwise a directory listing is generated by calling the :meth:`list_directory` method. This method uses :func:`os.listdir` to scan the directory, and returns a ``404`` error @@ -483,8 +483,6 @@ instantiation, of which this module provides three different variants: .. versionchanged:: 3.7 Support of the ``'If-Modified-Since'`` header. - The :class:`SimpleHTTPRequestHandler` class defines the following helpers: - .. method:: list_directory(path) Helper to list the contents of *path* when no index page is present. @@ -501,9 +499,8 @@ instantiation, of which this module provides three different variants: a MIME Content-type header. The default implementation looks the file's extension up in - :attr:`extensions_map`, falling back to - :func:`mimetypes.guess_file_type` and then to - :attr:`default_content_type`. + :attr:`extensions_map` and :func:`mimetypes.guess_file_type`, + using :attr:`default_content_type` as defaults. .. versionchanged:: 3.13 Add :func:`mimetypes.guess_file_type` as a fallback. From 33937b2e1c6edadc088dd0f70957b68a8da004e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?= <10796600+picnixz@users.noreply.github.com> Date: Sun, 5 Jul 2026 10:59:31 +0200 Subject: [PATCH 09/10] fixups? --- Doc/library/http.server.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index b92651b1fdcd181..fa7aa2caa5f873e 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -499,8 +499,9 @@ instantiation, of which this module provides three different variants: a MIME Content-type header. The default implementation looks the file's extension up in - :attr:`extensions_map` and :func:`mimetypes.guess_file_type`, - using :attr:`default_content_type` as defaults. + :attr:`extensions_map`, falling back to + :func:`mimetypes.guess_file_type` and then to + :attr:`default_content_type`. .. versionchanged:: 3.13 Add :func:`mimetypes.guess_file_type` as a fallback. From 9cb4da4ae0c98d922a3562f3d439255dd904e585 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?= <10796600+picnixz@users.noreply.github.com> Date: Sun, 5 Jul 2026 11:03:18 +0200 Subject: [PATCH 10/10] Update Doc/library/http.server.rst Co-authored-by: Stan Ulbrych --- Doc/library/http.server.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index fa7aa2caa5f873e..9c2ce2dffb185e9 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -493,7 +493,7 @@ instantiation, of which this module provides three different variants: .. method:: guess_type(path) - Guess the type of the file of given *path*. + Guess the type of the file at the given *path*. This returns a string of the form ``type/subtype``, usable for a MIME Content-type header.