Python A Simple Python Web Server

HTTPServer listens for connections and passes each request to a handler class you provide. The handler defines one method per HTTP method: do_GET, do_POST, do_DELETE and so on. Python calls the matching method and makes the request details available as attributes:

from http.server import BaseHTTPRequestHandler

class StatusHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == "/status":
            ...                     # build a response
        else:
            self.send_error(404)

SimpleHTTPRequestHandler, used by python -m http.server, is a ready-made handler that serves files from a folder. Custom handlers like this one decide everything themselves, which is a good way to see what web frameworks do behind the scenes.

An HTTP response has three parts, sent in order: a status line, headers, then a blank line and the body. The handler methods map onto them directly:

self.send_response(200)                                   # status line
self.send_header("Content-Type", "application/json; charset=utf-8")
self.send_header("Content-Length", str(len(body)))        # headers
self.end_headers()                                        # blank line
self.wfile.write(body)                                    # body

The order matters: once end_headers() is called, the headers have been sent and can't be changed, and anything written before it would corrupt the response. Content-Type tells the client how to interpret the body; Content-Length tells it how many bytes to expect.

self.send_error(404) writes a complete error response, status and HTML body included, in one call. Status codes follow the conventions covered in HTTP requests and REST APIs: 200 for success, 404 for an unknown path, 405 for an unsupported method, 400 for a malformed request.

self.wfile is a binary stream, so you write bytes, not str. JSON text must be encoded first:

import json
body = json.dumps({"robot": "ready", "battery": "86%"}).encode("utf-8")

Content-Length must be the length of those bytes, not the number of characters. They differ as soon as the text contains non-ASCII characters:

text = "Café"
print(len(text), len(text.encode("utf-8")))   # 4 5

If you send the character count, the client may cut off the end of the body or wait for bytes that never arrive. Declare the encoding in the header, charset=utf-8, so clients decode the body correctly. Reading a request body works the other way: read int(self.headers["Content-Length"]) bytes from self.rfile and decode them.

http.server is intended for development and learning. The Python documentation explicitly warns that it is not recommended for production: it only implements basic security checks, handles requests simply, and lacks the features a public site needs, such as HTTPS, robust request parsing, authentication and protection against slow or malicious clients.

Bind demo servers to 127.0.0.1 (localhost), so only your own computer can connect: HTTPServer(("127.0.0.1", 8080), Handler) or python -m http.server --bind 127.0.0.1. Binding to 0.0.0.0 exposes the server, and with SimpleHTTPRequestHandler every file in the folder, to anyone on your network.

Real applications run on a WSGI or ASGI server such as Gunicorn or Uvicorn, usually behind a reverse proxy like Nginx, with a framework such as Flask, Django or FastAPI handling routing. The concepts from this lesson, handlers, status, headers and byte bodies, are exactly what those layers manage for you.

Task: serve a local status route and verify a known path, an unknown path and the JSON content type. Extend the handler with a second route, /battery, and check all three paths:

routes = {"/status": {"robot": "ready"}, "/battery": {"level": 86}}

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        payload = routes.get(self.path)
        if payload is None:
            self.send_error(404)
            return
        body = json.dumps(payload).encode("utf-8")
        self.send_response(200)
        self.send_header("Content-Type", "application/json; charset=utf-8")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

Start it with the background-thread pattern from the example and request /status, /battery and /nope: expect two 200 JSON responses and one 404. For the worked check, the type written to the response body stream is bytes.

The http.server documentation lists handler attributes and the production warning. Continue with the Flask introduction and revisit HTTP and REST. Practise with the Python exercises and Python quiz.