python-clinic / Doc / library / http.server.rst

:mod:`http.server` --- HTTP servers

Source code: :source:`Lib/http/`

This module defines classes for implementing HTTP servers (Web servers).

One class, :class:`HTTPServer`, is a :class:`socketserver.TCPServer` subclass. It creates and listens at the HTTP socket, dispatching the requests to a handler. Code to create and run the server looks like this:

def run(server_class=HTTPServer, handler_class=BaseHTTPRequestHandler):
    server_address = ('', 8000)
    httpd = server_class(server_address, handler_class)

This class builds on the :class:`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.

The :class:`HTTPServer` must be given a RequestHandlerClass on instantiation, of which this module provides three different variants:

This class is used to handle the HTTP requests that arrive at the server. By itself, it cannot respond to any actual HTTP requests; it must be subclassed to handle each request method (e.g. GET or POST). :class:`BaseHTTPRequestHandler` provides a number of class and instance variables, and methods for use by subclasses.

The handler will parse the request and the headers, then call a method specific to the request type. The method name is constructed from the request. For example, for the request method SPAM, the :meth:`do_SPAM` method will be called with no arguments. All of the relevant information is stored in instance variables of the handler. Subclasses should not need to override or extend the :meth:`__init__` method.

:class:`BaseHTTPRequestHandler` has the following instance variables:

:class:`BaseHTTPRequestHandler` has the following class variables:

A :class:`BaseHTTPRequestHandler` instance has the following methods:

This class serves files from the current directory and below, directly mapping the directory structure to HTTP requests.

A lot of the work, such as parsing the request, is done by the base class :class:`BaseHTTPRequestHandler`. This class implements the :func:`do_GET` and :func:`do_HEAD` functions.

The following are defined as class-level attributes of :class:`SimpleHTTPRequestHandler`:

The :class:`SimpleHTTPRequestHandler` class defines the following methods:

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.

import http.server
import socketserver

PORT = 8000

Handler = http.server.SimpleHTTPRequestHandler

httpd = socketserver.TCPServer(("", PORT), Handler)

print("serving at port", PORT)

:mod:`http.server` can also be invoked directly using the :option:`-m` switch of the interpreter with a port number argument. Similar to the previous example, this serves files relative to the current directory.

python -m http.server 8000

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`.


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:

The :class:`CGIHTTPRequestHandler` defines the following method:

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 8000