From 6317921b5d3b9d3f7c398a22dc00fac5a52cb9d7 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:25:30 +0200 Subject: [PATCH 1/6] [3.13] gh-151945: fix Sphinx reference warnings in `http.server` docs (GH-153084) (cherry picked from commit 9f9787d83462f5b44cb59e3c69e7c1799612a33f) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/library/http.server.rst | 48 ++++++++++++++++++++++++++++++++++--- Doc/tools/.nitignore | 1 - 2 files changed, 45 insertions(+), 4 deletions(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index 4eadf28d3efb37..a55ef253795207 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) @@ -350,6 +360,14 @@ provides three different variants: This will be ``"SimpleHTTP/" + __version__``, where ``__version__`` is defined at the module level. + .. 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 @@ -374,7 +392,7 @@ 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 @@ -401,6 +419,30 @@ provides three different variants: .. versionchanged:: 3.7 Support of the ``'If-Modified-Since'`` header. + .. method:: list_directory(path) + + 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. + + .. method:: guess_type(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. + + 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`. + + .. versionchanged:: 3.13 + Add :func:`mimetypes.guess_file_type` as a fallback. + + 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:: @@ -419,7 +461,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`. .. class:: CGIHTTPRequestHandler(request, client_address, server) diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 5f760cdd278fdb..3aad71a103469a 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -13,7 +13,6 @@ Doc/library/asyncio-extending.rst Doc/library/asyncio-policy.rst Doc/library/email.charset.rst Doc/library/email.parser.rst -Doc/library/http.server.rst Doc/library/importlib.rst Doc/library/logging.config.rst Doc/library/logging.handlers.rst From 3ee7587cba0818a67cd09836767941acff728a18 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:58:34 +0200 Subject: [PATCH 2/6] fix CGI refs --- Doc/library/http.server.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index a55ef253795207..570a94f3cc4642 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -482,7 +482,8 @@ such as using different index file names by overriding the class attribute the other common server configuration is to treat special extensions as denoting CGI scripts. - The :func:`do_GET` and :func:`do_HEAD` functions are modified to run CGI scripts + The :func:`~SimpleHTTPRequestHandler.do_GET` and + :func:`~SimpleHTTPRequestHandler.do_HEAD` functions are modified to run CGI scripts and serve the output, instead of serving files, if the request leads to somewhere below the ``cgi_directories`` path. From e70bf19458270ab8284841fb73fbb5bd3fba3516 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:59:19 +0200 Subject: [PATCH 3/6] fix default content type 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 570a94f3cc4642..069d7749762ba3 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -437,7 +437,7 @@ provides three different variants: 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:`'application/octet-stream'`. .. versionchanged:: 3.13 Add :func:`mimetypes.guess_file_type` as a fallback. From bcf31c57beb423170df8ee0ee57c0a690b9f3e3f 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 12:00:36 +0200 Subject: [PATCH 4/6] Update Doc/library/http.server.rst --- Doc/library/http.server.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index 069d7749762ba3..acd6d6bc0c11db 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -483,7 +483,8 @@ such as using different index file names by overriding the class attribute denoting CGI scripts. The :func:`~SimpleHTTPRequestHandler.do_GET` and - :func:`~SimpleHTTPRequestHandler.do_HEAD` functions are modified to run CGI scripts + :func:`~SimpleHTTPRequestHandler.do_HEAD` functions + are modified to run CGI scripts and serve the output, instead of serving files, if the request leads to somewhere below the ``cgi_directories`` path. From 460021837e7b579a4e7333c7cbff8bce385fba8c 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 12:02:02 +0200 Subject: [PATCH 5/6] fix typo --- 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 acd6d6bc0c11db..c4c1cb8f2f140c 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -391,7 +391,7 @@ provides three different variants: The request is mapped to a local file by interpreting the request as a path relative to the current working directory. - If the request was mapped to a directory, the directory is checked for a + If the request was mapped to a directory, the directory is checked for 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 From 4670c4ac12d4d59d50d6174951ca545e03971ec8 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 12:06:51 +0200 Subject: [PATCH 6/6] Update Doc/library/http.server.rst --- 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 c4c1cb8f2f140c..57a6f1511963bc 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -437,7 +437,7 @@ provides three different variants: 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:`'application/octet-stream'`. + ``'application/octet-stream'``. .. versionchanged:: 3.13 Add :func:`mimetypes.guess_file_type` as a fallback.