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

Source code: :source:Lib/http/server.py

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)
httpd.serve_forever()


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)
httpd.serve_forever()


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

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:

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