[3.13] gh-130160: use .. program:: directive for documenting http.server CLI (GH-131010) (#131293)

gh-130160: use `.. program::` directive for documenting `http.server` CLI (GH-131010)
(cherry picked from commit 7ae9c5dd25)

Co-authored-by: donBarbos <donbarbos@proton.me>
This commit is contained in:
Miss Islington (bot) 2025-03-15 20:12:40 +01:00 committed by GitHub
parent 5646f6f739
commit b7e15a93b4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -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)
@ -510,25 +467,85 @@ following command runs an HTTP/1.1 conformant server::
Retaining it could lead to further :ref:`security considerations
<http.server-security>`.
:class:`CGIHTTPRequestHandler` can be enabled in the command line by passing
the ``--cgi`` option::
python -m http.server --cgi
.. _http-server-cli:
.. deprecated-removed:: 3.13 3.15
Command-line interface
----------------------
:mod:`http.server` command line ``--cgi`` support is being removed
because :class:`CGIHTTPRequestHandler` is being removed.
: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 <address>
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 <dir>
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 <version>
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