From 52282b83b712e0c419b3e21e045af86f0aacd2d8 Mon Sep 17 00:00:00 2001 From: donBarbos Date: Sat, 15 Mar 2025 20:28:56 +0400 Subject: [PATCH 1/3] gh-130160: use `.. program::` directive for documenting `http.server` CLI (#131010) (cherry picked from commit 7ae9c5dd25cccfc4e44fae6c6974ab9f32c5e985) --- Doc/library/http.server.rst | 117 +++++++++++++++++++++--------------- 1 file changed, 69 insertions(+), 48 deletions(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index d2e43f03f94b2d..4c668e12acaefd 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -418,49 +418,6 @@ the current directory:: such as using different index file names by overriding the class attribute :attr:`index_pages`. -.. _http-server-cli: - -:mod:`http.server` can also be invoked directly using the :option:`-m` -switch of the interpreter. Similar to -the previous example, this serves files relative to the current directory:: - - python -m http.server - -The server listens to port 8000 by default. The default can be overridden -by passing the desired port number as an argument:: - - python -m http.server 9000 - -By default, the server binds itself to all interfaces. The option ``-b/--bind`` -specifies a specific address to which it should bind. Both IPv4 and IPv6 -addresses are supported. For example, the following command causes the server -to bind to localhost only:: - - python -m http.server --bind 127.0.0.1 - -.. versionchanged:: 3.4 - Added the ``--bind`` option. - -.. versionchanged:: 3.8 - Support IPv6 in the ``--bind`` option. - -By default, the server uses the current directory. The option ``-d/--directory`` -specifies a directory to which it should serve the files. For example, -the following command uses a specific directory:: - - python -m http.server --directory /tmp/ - -.. versionchanged:: 3.7 - Added the ``--directory`` option. - -By default, the server is conformant to HTTP/1.0. The option ``-p/--protocol`` -specifies the HTTP version to which the server is conformant. For example, the -following command runs an HTTP/1.1 conformant server:: - - python -m http.server --protocol HTTP/1.1 - -.. versionchanged:: 3.11 - Added the ``--protocol`` option. .. class:: CGIHTTPRequestHandler(request, client_address, server) @@ -502,20 +459,84 @@ following command runs an HTTP/1.1 conformant server:: Note that CGI scripts will be run with UID of user nobody, for security reasons. Problems with the CGI script will be translated to error 403. -:class:`CGIHTTPRequestHandler` can be enabled in the command line by passing -the ``--cgi`` option:: - python -m http.server --cgi +.. _http-server-cli: + +Command-line interface +---------------------- + +:mod:`http.server` can also be invoked directly using the :option:`-m` +switch of the interpreter. The following example illustrates how to serve +files relative to the current directory:: + + python -m http.server [OPTIONS] [port] + +The following options are accepted: + +.. program:: http.server + +.. option:: port + + The server listens to port 8000 by default. The default can be overridden + by passing the desired port number as an argument:: + + python -m http.server 9000 + +.. option:: -b, --bind
+ + Specifies a specific address to which it should bind. Both IPv4 and IPv6 + addresses are supported. By default, the server binds itself to all + interfaces. For example, the following command causes the server to bind + to localhost only:: + + python -m http.server --bind 127.0.0.1 + + .. versionadded:: 3.4 + + .. versionchanged:: 3.8 + Support IPv6 in the ``--bind`` option. + +.. option:: -d, --directory + + Specifies a directory to which it should serve the files. By default, + the server uses the current directory. For example, the following command + uses a specific directory:: + + python -m http.server --directory /tmp/ + + .. versionadded:: 3.7 + +.. option:: -p, --protocol + + Specifies the HTTP version to which the server is conformant. By default, + the server is conformant to HTTP/1.0. For example, the following command + runs an HTTP/1.1 conformant server:: + + python -m http.server --protocol HTTP/1.1 + + .. versionadded:: 3.11 + +.. option:: --cgi + + :class:`CGIHTTPRequestHandler` can be enabled in the command line by passing + the ``--cgi`` option:: + + python -m http.server --cgi + + .. deprecated-removed:: 3.13 3.15 + + :mod:`http.server` command line ``--cgi`` support is being removed + because :class:`CGIHTTPRequestHandler` is being removed. .. warning:: - :class:`CGIHTTPRequestHandler` and the ``--cgi`` command line option + :class:`CGIHTTPRequestHandler` and the ``--cgi`` command-line option are not intended for use by untrusted clients and may be vulnerable to exploitation. Always use within a secure environment. .. _http.server-security: -Security Considerations +Security considerations ----------------------- .. index:: pair: http.server; security From 3c6bf2d71a94858d0e8c903db552b2ec25a35cd4 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sat, 15 Mar 2025 21:12:29 +0200 Subject: [PATCH 2/3] Update Doc/library/http.server.rst --- Doc/library/http.server.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index 4c668e12acaefd..2de61c4c7123d6 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -534,6 +534,7 @@ The following options are accepted: are not intended for use by untrusted clients and may be vulnerable to exploitation. Always use within a secure environment. + .. _http.server-security: Security considerations From c63b2038bee7afe26d0861a74a95be20ef130fa1 Mon Sep 17 00:00:00 2001 From: donBarbos Date: Sat, 15 Mar 2025 23:20:44 +0400 Subject: [PATCH 3/3] Update http.server.rst Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- Doc/library/http.server.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index 2de61c4c7123d6..35673956116035 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -523,11 +523,6 @@ The following options are accepted: python -m http.server --cgi - .. deprecated-removed:: 3.13 3.15 - - :mod:`http.server` command line ``--cgi`` support is being removed - because :class:`CGIHTTPRequestHandler` is being removed. - .. warning:: :class:`CGIHTTPRequestHandler` and the ``--cgi`` command-line option