From f1f90879d2b7d5604feb3a9519db6e3898629ac5 Mon Sep 17 00:00:00 2001 From: donBarbos Date: Sun, 9 Mar 2025 18:42:17 +0400 Subject: [PATCH 1/5] use `.. program::` directive for documenting `http.server` CLI --- Doc/library/http.server.rst | 61 ++++++++++++++++++++++--------------- 1 file changed, 36 insertions(+), 25 deletions(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index 1197b575c00455..277aaf94412af9 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -420,47 +420,58 @@ such as using different index file names by overriding the class attribute .. _http-server-cli: +Command-line interface +---------------------- + :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 + python -m http.server [--cgi] [-b ADDRESS] [-d DIRECTORY] [-p VERSION] [port] + +.. 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:: -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 - python -m http.server 9000 +.. option:: -b, --bind
-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:: + 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 + python -m http.server --bind 127.0.0.1 -.. versionchanged:: 3.4 - Added the ``--bind`` option. + .. versionadded:: 3.4 -.. versionchanged:: 3.8 - Support IPv6 in 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:: +.. 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 - python -m http.server --directory /tmp/ +.. option:: -p, --protocol -.. versionchanged:: 3.7 - Added the ``--directory`` option. + 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:: -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 - python -m http.server --protocol HTTP/1.1 + .. versionadded:: 3.11 -.. versionchanged:: 3.11 - Added the ``--protocol`` option. .. class:: CGIHTTPRequestHandler(request, client_address, server) From f55d340040fe74ee7087bd2a3eb8f1b24ed2bb40 Mon Sep 17 00:00:00 2001 From: donBarbos Date: Mon, 10 Mar 2025 07:11:54 +0400 Subject: [PATCH 2/5] Move --cgi flag up --- Doc/library/http.server.rst | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index 277aaf94412af9..87151c2aaeb1cb 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -427,7 +427,9 @@ Command-line interface switch of the interpreter. Similar to the previous example, this serves files relative to the current directory:: - python -m http.server [--cgi] [-b ADDRESS] [-d DIRECTORY] [-p VERSION] [port] + python -m http.server + +The following options are accepted: .. program:: http.server @@ -472,6 +474,24 @@ the previous example, this serves files relative to the current directory:: .. 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 + are not intended for use by untrusted clients and may be vulnerable + to exploitation. Always use within a secure environment. + .. class:: CGIHTTPRequestHandler(request, client_address, server) @@ -521,21 +541,6 @@ the previous example, this serves files relative to the current directory:: Retaining it could lead to further :ref:`security considerations `. -: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 - are not intended for use by untrusted clients and may be vulnerable - to exploitation. Always use within a secure environment. .. _http.server-security: From 034336cf2765abbc8d5dbf4ff7bded51b4de1aef Mon Sep 17 00:00:00 2001 From: donBarbos Date: Sat, 15 Mar 2025 16:34:15 +0400 Subject: [PATCH 3/5] Add suggestions --- Doc/library/http.server.rst | 101 ++++++++++++++++++------------------ 1 file changed, 51 insertions(+), 50 deletions(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index 87151c2aaeb1cb..3aa15e787abf04 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -418,6 +418,56 @@ the current directory:: such as using different index file names by overriding the class attribute :attr:`index_pages`. + +.. class:: CGIHTTPRequestHandler(request, client_address, server) + + This class is used to serve either files or output of CGI scripts from the + current directory and below. Note that mapping HTTP hierarchic structure to + local directory structure is exactly as in :class:`SimpleHTTPRequestHandler`. + + .. note:: + + CGI scripts run by the :class:`CGIHTTPRequestHandler` class cannot execute + redirects (HTTP code 302), because code 200 (script output follows) is + sent prior to execution of the CGI script. This pre-empts the status + code. + + The class will however, run the CGI script, instead of serving it as a file, + if it guesses it to be a CGI script. Only directory-based CGI are used --- + 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 + and serve the output, instead of serving files, if the request leads to + somewhere below the ``cgi_directories`` path. + + The :class:`CGIHTTPRequestHandler` defines the following data member: + + .. attribute:: cgi_directories + + This defaults to ``['/cgi-bin', '/htbin']`` and describes directories to + treat as containing CGI scripts. + + The :class:`CGIHTTPRequestHandler` defines the following method: + + .. method:: do_POST() + + This method serves the ``'POST'`` request type, only allowed for CGI + scripts. Error 501, "Can only POST to CGI scripts", is output when trying + to POST to a non-CGI url. + + 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. + + .. deprecated-removed:: 3.13 3.15 + + :class:`CGIHTTPRequestHandler` is being removed in 3.15. CGI has not + been considered a good way to do things for well over a decade. This code + has been unmaintained for a while now and sees very little practical use. + Retaining it could lead to further :ref:`security considerations + `. + + .. _http-server-cli: Command-line interface @@ -427,7 +477,7 @@ Command-line interface switch of the interpreter. Similar to the previous example, this serves files relative to the current directory:: - python -m http.server + python -m http.server [OPTIONS] [port] The following options are accepted: @@ -493,55 +543,6 @@ The following options are accepted: to exploitation. Always use within a secure environment. -.. class:: CGIHTTPRequestHandler(request, client_address, server) - - This class is used to serve either files or output of CGI scripts from the - current directory and below. Note that mapping HTTP hierarchic structure to - local directory structure is exactly as in :class:`SimpleHTTPRequestHandler`. - - .. note:: - - CGI scripts run by the :class:`CGIHTTPRequestHandler` class cannot execute - redirects (HTTP code 302), because code 200 (script output follows) is - sent prior to execution of the CGI script. This pre-empts the status - code. - - The class will however, run the CGI script, instead of serving it as a file, - if it guesses it to be a CGI script. Only directory-based CGI are used --- - 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 - and serve the output, instead of serving files, if the request leads to - somewhere below the ``cgi_directories`` path. - - The :class:`CGIHTTPRequestHandler` defines the following data member: - - .. attribute:: cgi_directories - - This defaults to ``['/cgi-bin', '/htbin']`` and describes directories to - treat as containing CGI scripts. - - The :class:`CGIHTTPRequestHandler` defines the following method: - - .. method:: do_POST() - - This method serves the ``'POST'`` request type, only allowed for CGI - scripts. Error 501, "Can only POST to CGI scripts", is output when trying - to POST to a non-CGI url. - - 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. - - .. deprecated-removed:: 3.13 3.15 - - :class:`CGIHTTPRequestHandler` is being removed in 3.15. CGI has not - been considered a good way to do things for well over a decade. This code - has been unmaintained for a while now and sees very little practical use. - Retaining it could lead to further :ref:`security considerations - `. - - .. _http.server-security: Security Considerations From 79f707495775740b50e740df3177f40a854e889b Mon Sep 17 00:00:00 2001 From: donBarbos Date: Sat, 15 Mar 2025 16:42:57 +0400 Subject: [PATCH 4/5] Correct example sentense --- Doc/library/http.server.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index 3aa15e787abf04..0f872b81687022 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -474,8 +474,8 @@ Command-line interface ---------------------- :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:: +switch of the interpreter. The following example illustrates how to serve +files relative to the current directory:: python -m http.server [OPTIONS] [port] From b474a30a9389c7e6cecf265ad7fb24e43105207f Mon Sep 17 00:00:00 2001 From: donBarbos Date: Sat, 15 Mar 2025 20:20:56 +0400 Subject: [PATCH 5/5] accept suggestions --- Doc/library/http.server.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index 0f872b81687022..1b00b09bf6da7f 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -538,14 +538,14 @@ The following options are accepted: .. 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