Skip to content
Tutorials Center
My learning

Topics

Python Reference ยท Standard Library: Concurrency, Network and Tools

The http.server and urllib modules

Reference for Python's http.server, http.HTTPStatus and urllib.request: serve files, write a tiny handler, build a Request, and understand what runs in a browser.

Python's standard library has a small web server and a small web client. http.server serves files or runs your own request handler, and urllib.request fetches URLs. They are meant for learning, quick tools and tests, not for production traffic: the server handles requests plainly and has no hardening, and for serious clients most people use the third-party requests or httpx.

http.HTTPStatus is an enum that gives every status code a name and a standard phrase, and it is useful with either side.

Python
# From a shell: serve the current folder at http://localhost:8000
#   python -m http.server 8000

Try it

The browser runner has no network and cannot listen on ports, so these examples exercise the parts that work offline. The server and client code that follows them is read-only.

Python Status codes and request objects

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Fetching fails without a network

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A tiny JSON server and client for your own computer (read-only):

Python
import json
import threading
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.request import urlopen

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        body = json.dumps({"path": self.path}).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def log_message(self, format, *args):    # silence the default access log
        pass

server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
threading.Thread(target=server.serve_forever, daemon=True).start()

url = f"http://127.0.0.1:{server.server_port}/hello"
with urlopen(url) as response:
    print(response.status, json.load(response))   # 200 {'path': '/hello'}
server.shutdown()

Syntax

Python
http.server.HTTPServer(server_address, RequestHandlerClass)
http.server.ThreadingHTTPServer(server_address, RequestHandlerClass)
urllib.request.urlopen(url, data=None, timeout=..., *, context=None)
urllib.request.Request(url, data=None, headers={}, method=None)
Name Description
server_address A (host, port) tuple. Port 0 lets the OS choose; read it back from server.server_port.
RequestHandlerClass A subclass of BaseHTTPRequestHandler (or SimpleHTTPRequestHandler, which serves files).
url A string or a Request object.
data Bytes for the request body. Providing it makes the default method POST.
headers Dictionary of request headers.
timeout Seconds to wait for the connection and reads.

Handler pieces: define do_GET, do_POST and so on; use self.path, self.headers, self.rfile (request body), send_response(), send_header(), end_headers() and self.wfile (response body).

Return value of urlopen(): a response object usable in a with block, with status, headers, read() and getheader().

Raises: urllib.error.HTTPError for 4xx and 5xx answers (it is also a response you can read), urllib.error.URLError for connection problems.

Usage notes

  • Not for production. http.server does no authentication, no HTTPS and very little input checking. Use it for local previews and tests, or a real framework and server for live sites.
  • python -m http.server serves the current directory; add --bind 127.0.0.1 to keep it off other machines, and --directory path to choose a folder.
  • Always send Content-Length (or close the connection) so the client knows where the body ends.
  • Use ThreadingHTTPServer when one slow request should not block the rest.
  • urlopen() needs a timeout. The default waits indefinitely.
  • Read bytes, then decode. response.read() gives bytes; decode with the charset from response.headers.get_content_charset().
  • HTTPError for error statuses. Catch HTTPError before URLError, because it is a subclass.
  • Query strings are easiest to build with urllib.parse.urlencode.
  • Cannot run in the browser runner: no sockets and no network.