===========================================================
BaseHTTPServer -- base classes for implementing web servers
===========================================================
.. module:: BaseHTTPServer
:synopsis: Provides base classes for implementing web servers.
:Purpose: BaseHTTPServer includes classes that can form the basis of a web server.
:Python Version: 1.4 and later
:mod:`BaseHTTPServer` uses classes from :mod:`SocketServer` to create
base classes for making HTTP servers. :class:`HTTPServer` can be used
directly, but the :class:`BaseHTTPRequestHandler` is intended to be
extended to handle each protocol method (GET, POST, etc.).
HTTP GET
========
To add support for an HTTP method in your request handler class,
implement the method :func:`do_METHOD`, replacing *METHOD* with the
name of the HTTP method. For example, :func:`do_GET`, :func:`do_POST`,
etc. For consistency, the method takes no arguments. All of the
parameters for the request are parsed by
:class:`BaseHTTPRequestHandler` and stored as instance attributes of
the request instance.
This example request handler illustrates how to return a response to the
client and some of the local attributes which can be useful in building the
response:
.. include:: BaseHTTPServer_GET.py
:literal:
:start-after: #end_pymotw_header
The message text is assembled and then written to :attr:`wfile`, the
file handle wrapping the response socket. Each response needs a
response code, set via :func:`send_response`. If an error code is used
(404, 501, etc.), an appropriate default error message is included in
the header, or a message can be passed with the error code.
To run the request handler in a server, pass it to the constructor of
HTTPServer, as in the ``__main__`` processing portion of the sample script.
Then start the server:
::
$ python BaseHTTPServer_GET.py
Starting server, use <Ctrl-C> to stop
In a separate terminal, use :command:`curl` to access it:
::
$ curl -i http://localhost:8080/?foo=barHTTP/1.0 200 OK
Server: BaseHTTP/0.3 Python/2.5.1
Date: Sun, 09 Dec 2007 16:00:34 GMT
CLIENT VALUES:
client_address=('127.0.0.1', 51275) (localhost)
command=GET
path=/?foo=bar
real path=/
query=foo=bar
request_version=HTTP/1.1
SERVER VALUES:
server_version=BaseHTTP/0.3
sys_version=Python/2.5.1
protocol_version=HTTP/1.0
HTTP POST
=========
Supporting POST requests is a little more work, because the base class
does not parse the form data for us. The :mod:`cgi` module provides
the :class:`FieldStorage` class which knows how to parse the form, if
it is given the correct inputs.
.. include:: BaseHTTPServer_POST.py
:literal:
:start-after: #end_pymotw_header
:command:`curl` can include form data in the message it posts to the
server. The last argument, ``-F datafile=@BaseHTTPServer_GET.py``,
posts the contents of the file ``BaseHTTPServer_GET.py`` to illustrate
reading file data from the form.
::
$ curl http://localhost:8080/ -F name=dhellmann -F foo=bar -F datafile=@BaseHTTPServer_GET.py
Client: ('127.0.0.1', 51128)
Path: /
Form data:
name=dhellmann
foo=bar
Uploaded datafile (2222 bytes)
Threading and Forking
=====================
:class:`HTTPServer` is a simple subclass of
:class:`SocketServer.TCPServer`, and does not use multiple threads or
processes to handle requests. To add threading or forking, create a
new class using the appropriate mix-in from :mod:`SocketServer`.
.. include:: BaseHTTPServer_threads.py
:literal:
:start-after: #end_pymotw_header
Each time a request comes in, a new thread or process is created to
handle it:
::
$ curl http://localhost:8080/
Thread-1
$ curl http://localhost:8080/
Thread-2
$ curl http://localhost:8080/
Thread-3
Swapping :class:`ForkingMixIn` for :class:`ThreadingMixIn` above would
achieve similar results, using separate processes instead of threads.
Handling Errors
===============
Error handling is made easy with :meth:`send_error()`. Simply pass the
appropriate error code and an optional error message, and the entire
response (with headers, status code, and body) is generated
automatically.
.. include:: BaseHTTPServer_errors.py
:literal:
:start-after: #end_pymotw_header
In this case, a 404 error is always returned.
::
$ curl -i http://localhost:8080/
HTTP/1.0 404 Not Found
Server: BaseHTTP/0.3 Python/2.5.1
Date: Sun, 09 Dec 2007 15:49:44 GMT
Content-Type: text/html
Connection: close
<head>
<title>Error response</title>
</head>
<body>
<h1>Error response</h1>
<p>Error code 404.
<p>Message: Not Found.
<p>Error code explanation: 404 = Nothing matches the given URI.
</body>
Setting Headers
===============
The :mod:`send_header` method adds header data to the HTTP response.
It takes two arguments, the name of the header and the value.
.. include:: BaseHTTPServer_send_header.py
:literal:
:start-after: #end_pymotw_header
This example sets the ``Last-Modified`` header to the current
timestamp formatted according to :rfc:`2822`.
::
$ curl -i http://localhost:8080/
HTTP/1.0 200 OK
Server: BaseHTTP/0.3 Python/2.7
Date: Sun, 10 Oct 2010 13:58:32 GMT
Last-Modified: Sun, 10 Oct 2010 13:58:32 -0000
Response body
.. seealso::
`BaseHTTPServer <http://docs.python.org/library/basehttpserver.html>`_
The standard library documentation for this module.
:mod:`SocketServer`
The SocketServer module provides the base class which handles
the raw socket connection.