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.
# 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.
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.
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):
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
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.serverdoes 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.serverserves the current directory; add--bind 127.0.0.1to keep it off other machines, and--directory pathto choose a folder.- Always send
Content-Length(or close the connection) so the client knows where the body ends. - Use
ThreadingHTTPServerwhen one slow request should not block the rest. urlopen()needs a timeout. The default waits indefinitely.- Read bytes, then decode.
response.read()givesbytes; decode with the charset fromresponse.headers.get_content_charset(). HTTPErrorfor error statuses. CatchHTTPErrorbeforeURLError, 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.
Related
urllib.parse,socket,jsonthreading- Lessons: Networking, Web development