Mastering WSGI: A Beginner’s Guide to Python Web Servers

WSGI Introduction

WSGI (Web Server Gateway Interface) is a specification that defines how a web server communicates with a web application and how the application processes requests, as described in PEP 3333. Both the server and the application must conform to this interface.

Implementations include the built‑in wsgiref, werkzeug.serving, and twisted.web. Popular frameworks that run on WSGI are Bottle, Flask, and Django.

WSGI Basics

A WSGI server simply forwards the client request to a WSGI application and returns the application's response to the client. Middleware can sit between the server and the application, forming a stack.

1. WSGI Application Interface

The application must be a callable object (function, method, class instance with __call__) that accepts two arguments: an environ dictionary containing request information, and a start_response callback for setting the HTTP status and headers. The callable returns an iterable response body, typically a list of byte strings.

2. Environment

An example program environment.py returns the contents of the environ dictionary to the client. When accessed via a browser or tools like curl, the environment data is displayed, and the program prints the same information to the terminal.

3. Iterable Response

Returning a plain string makes the response iterator yield one byte at a time, causing slow transmission. It is recommended to return a list, e.g., return [response_body]. If the response consists of multiple strings, the Content‑Length header should equal the sum of their lengths.

Parsing GET Requests

Running environment.py and visiting

http://localhost:8051/?age=10&hobbies=software&hobbies=tunning

shows the query string in the environment. The cgi.parse_qs() function conveniently parses QUERY_STRING, and cgi.escape() should be used to prevent script injection. Sample code (illustrated in the images) demonstrates handling GET parameters and generating a dynamic page.

Parsing POST Requests

For POST requests, the query string resides in the request body, accessible via environ['wsgi.input'], which behaves like a file object. The CONTENT_LENGTH header indicates the body size but may be missing, so reading the body should be wrapped in a try/except block. Example code (shown in the images) illustrates processing POST data.

Python WSGI Fundamentals

The WSGI server processes each HTTP request by invoking the application callable with the environ dictionary and start_response. The application returns an iterable that the server sends to the client.

Middleware sits between the server and the application, allowing additional processing of requests and responses.

Further Learning

With these basics, beginners can start building simple web frameworks, but creating complex frameworks requires deeper knowledge of WSGI. Reading the source code of mature frameworks like Bottle and Flask is recommended for advanced learning.