Add suggestions

python · hugovk · Mar 15, 2025 · Mar 9, 2025 · Mar 10, 2025 · Mar 15, 2025
commit 034336cf2765abbc8d5dbf4ff7bded51b4de1aef
diff --git 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-security>`.
+
+
 .. _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>`.
-
-
 .. _http.server-security:

 Security Considerations