WSGI

What it is and why it exists

WSGI is the Python Web Server Gateway Interface defined by PEP 3333. It specifies how a web server represents an HTTP request as Python data, calls an application, and receives a status, response headers, and body. Frameworks and servers can depend on that shared protocol, so a Flask or Django application doesn’t need a custom adapter for every WSGI server.

WSGI solves in-process interface compatibility; it isn’t a complete HTTP server specification. The server owns sockets, HTTP parsing, connection management, and client disconnects, while the application owns routing, domain logic, and response content. Reverse proxies, TLS, worker counts, and deployment topology also sit outside the WSGI contract.

You encounter WSGI in framework application objects, server startup targets, and middleware. A server typically imports an object named like module:application and calls it for each request. Middleware accepts the server’s call and then acts as a server to the next application, so components compose through the same interface.

WSGI describes a synchronous call: an ordinary callable must complete one request in its current execution context. It neither requires the server to use only one thread or process nor guarantees that global state is safe. A server can execute several independent WSGI calls concurrently with processes, threads, or another implementation strategy.

Long-lived connections, WebSockets, and native asynchronous send and receive operations aren’t WSGI’s target. Compare ASGI when you need those capabilities, but mechanically changing a mature synchronous application to async def doesn’t automatically increase capacity. Choose from protocol requirements, dependencies, and measured waiting time rather than a framework label.

How it works

One request revolves around three objects: the server supplies environ and start_response, and the application returns an iterable . environ describes the request and server capabilities, start_response() submits the status and headers, and the iterable supplies the body in chunks. Together they make the protocol; checking only the function signature isn’t enough.

The returns in the diagram don’t imply that the application has produced the whole body. It can return a list or a generator that runs later and yields chunks. The server obtains the body as it iterates and calls close() when the result provides that method.

The application callable

A minimal application has the shape application(environ, start_response). It computes the status and headers, calls start_response() before making the first body chunk available, and returns an iterable. Every item yielded by the iterable must be bytes, apart from an empty response that yields no items.

In start_response(status, response_headers, exc_info=None), status is a string such as "200 OK". The headers are a list of string (name, value) pairs. The third argument is only for an application trying to replace unsent headers while handling an exception; an ordinary success path shouldn’t pass it.

start_response() returns the legacy write() callable for compatibility with an early push style. New code should return a body iterable instead of relying on write(). Mixing both body paths makes ordering, streaming, and error handling harder to reason about.

Requests in environ

WSGI environ is an ordinary dictionary whose keys and values follow protocol rules. CGI-style keys describe the HTTP request, wsgi.* keys describe the protocol and server capabilities, and servers or middleware may add collision-resistant extension keys. An application shouldn’t assume that every HTTP request header has a corresponding key.

Except for CONTENT_TYPE and CONTENT_LENGTH, request headers normally become uppercase, replace hyphens with underscores, and gain an HTTP_ prefix. For example, X-Request-ID maps to HTTP_X_REQUEST_ID. This is the server’s normalized view, not proof of trust: a public client can forge a header unless a trusted proxy explicitly strips and replaces it.

The application reads a request body from wsgi.input; it doesn’t receive an already parsed object in environ. It should validate CONTENT_LENGTH and its own size limit before reading the permitted bytes. Media type handling, character decoding, and structural parsing such as JSON belong to the application or framework.

Status, headers, and body

The status and response headers must reach start_response() before the first body chunk can be sent by the server. An application can’t generate hop-by-hop response headers such as Connection or Transfer-Encoding, because the server manages the current HTTP connection. It may set Content-Length when the byte count is known exactly, never by guessing from a character count.

The body’s byte boundary matters. The application encodes text as bytes with a selected encoding, then calculates Content-Length from those bytes. Returning a Python str violates the protocol even when it contains only ASCII, and a validator or server should reject it.

The server must handle chunks in iterable order and complete each chunk’s transmission before requesting the next one. WSGI doesn’t promise that each yield becomes one network packet or that a proxy immediately passes it to the client. An application can produce data incrementally, but end-to-end buffering still needs verification in the real deployment path.

The middleware chain

Middleware wraps another WSGI application while presenting the same protocol to its caller. It can change environ, wrap start_response() to observe status or headers, or wrap the returned iterable. Authentication, tracing, exception mapping, and security headers often live at this layer.

Transparent middleware must preserve protocol details it doesn’t change. If it consumes a downstream iterable, it must preserve body order and ensure the downstream close() is called; if it wraps start_response(), it must accept and forward exc_info. Collecting the entire response in memory just to log a status code silently breaks streaming.

Middleware order changes behavior. Exception middleware outside authentication can translate failures from the authentication layer; placed inside, it never sees them. Test ordering as part of the architecture rather than checking every middleware unit only in isolation.

Concurrency is declared by the server

wsgi.multithread, wsgi.multiprocess, and wsgi.run_once are booleans that describe the execution environment, not configuration commands from the application to the server. An application can use them to judge whether an optimization is safe, but correctness is usually more robust when it doesn’t depend on one worker model. Database pools, caches, and locks need scopes that match the actual process and thread boundaries.

A synchronous protocol means one call can’t yield control to an ASGI-style event loop while it waits. The server can still let other threads or processes serve other requests. It is therefore wrong to derive “WSGI handles only one request at a time” from “WSGI is synchronous.”

Examples

The three examples use only the Python standard library. Their output comes from running each file with the local python3; the protocol they use was checked against the Python 3.14 documentation and PEP 3333.

A minimal application with protocol validation

The first application reads a method, path, and query string and returns an already encoded body list. A small invoker builds a base environment with setup_testing_defaults() and lets wsgiref.validate.validator() check WSGI assertions on both sides.

The invoker also fulfills server-side duties: it records status and headers, consumes the body, and calls close() when available. validator() belongs in development and tests. It is middleware that checks protocol assertions, not a production security boundary or a proof that the domain logic is correct.

This example returns the whole body at once, so it can set an exact Content-Length. len(body) counts bytes. Calling len() on the Unicode string first would give a different result when it contains non-ASCII characters.

Reading a bounded JSON body

The second application separates the transport boundary from the parsing boundary. It converts CONTENT_LENGTH to an integer and applies a 64-byte limit, reads exactly that permitted length from wsgi.input, and only then parses JSON.

from io import BytesIO
import json

MAX_BODY = 64

def respond(start_response, status, payload):
    body = json.dumps(payload, separators=(",", ":")).encode()
    start_response(status, [("Content-Type", "application/json"),
                            ("Content-Length", str(len(body)))])
    return [body]


def application(environ, start_response):
    raw_length = environ.get("CONTENT_LENGTH", "")
    try:
        length = int(raw_length or "0")
    except ValueError:
        return respond(start_response, "400 Bad Request", {"error": "bad length"})
    if length < 0 or length > MAX_BODY:
        return respond(start_response, "413 Content Too Large", {"error": "too large"})
    try:
        document = json.loads(environ["wsgi.input"].read(length))
    except (UnicodeDecodeError, json.JSONDecodeError):
        return respond(start_response, "400 Bad Request", {"error": "bad json"})
    return respond(start_response, "200 OK", {"received": document})

def invoke(payload):
    environ = {"CONTENT_LENGTH": str(len(payload)), "wsgi.input": BytesIO(payload)}
    captured = []

    def start_response(status, headers, exc_info=None):
        captured.append(status)
        return lambda data: None

    body = b"".join(application(environ, start_response))
    return captured[0], body.decode()


print(*invoke(b'{"order_id":7}'), sep="\n")
print(*invoke(b"x" * 65), sep="\n")

200 OK
{"received":{"order_id":7}}
413 Content Too Large
{"error":"too large"}

The 64-byte number is an explicit test boundary for this runnable example, not a production recommendation. A real service should derive its limit from the endpoint, media type, and infrastructure constraints, then test server behavior when the declared length and actual transfer disagree.

This small application doesn’t enforce a media type or distinguish an empty body from a JSON parsing error. Frameworks normally provide fuller request objects and error mapping, but the same byte count, input stream, and resource limit remain underneath.

Middleware that preserves streaming

The third example wraps start_response() to log the method, path, and final status, then adds a security response header. The middleware returns the downstream generator directly instead of collecting the body into a list.

class SecurityHeaderMiddleware:
    def __init__(self, app):
        self.app = app

    def __call__(self, environ, start_response):
        method = environ["REQUEST_METHOD"]
        path = environ["PATH_INFO"]

        def add_header(status, headers, exc_info=None):
            print(f"{method} {path} -> {status.split()[0]}")
            updated = [*headers, ("X-Content-Type-Options", "nosniff")]
            return start_response(status, updated, exc_info)

        return self.app(environ, add_header)


def application(environ, start_response):
    start_response("200 OK", [("Content-Type", "text/plain")])
    yield b"part-1"
    yield b"|part-2"


captured = {}


def start_response(status, headers, exc_info=None):
    captured.update(status=status, headers=headers)
    return lambda data: None


wrapped = SecurityHeaderMiddleware(application)
result = wrapped({"REQUEST_METHOD": "GET", "PATH_INFO": "/report"}, start_response)
try:
    body = b"".join(result)
finally:
    result.close()

print(captured["headers"][-1])
print(body.decode())

GET /report -> 200
('X-Content-Type-Options', 'nosniff')
part-1|part-2

Because application() is a generator function, its body doesn’t run until the server begins iteration, so the log also appears then. The middleware doesn’t consume the result itself, leaving iteration and closure owned by the outer server.

If middleware needs to change the body, it must return its own wrapping iterable and close the downstream result from that wrapper’s close(). A generator’s finally can clean up resources that generator has acquired; it doesn’t replace explicit forwarding of the downstream lifecycle.

Pitfalls

Mistaking synchronous for single-threaded

Fix: inspect the real server configuration and wsgi.multithread and wsgi.multiprocess, then design state for those boundaries. Put cross-request data in external storage with an explicit consistency contract, and document the per-process scope of in-memory caches and connection pools.

Returning text instead of bytes

Fix: choose a character encoding and call .encode() explicitly. Declare that encoding in Content-Type, calculate Content-Length from the encoded bytes, and use wsgiref.validate in tests to catch type violations.

Reading the input stream without a bound

Fix: validate missing, empty, negative, and nonnumeric lengths before applying an endpoint-specific byte limit. For a streaming upload, read bounded chunks, set compatible limits in the server or proxy, and handle an early client disconnect.

Breaking the lifecycle in middleware

Fix: return the downstream iterable directly when the body is unchanged. When changing it, implement a wrapper that forwards order, exceptions, and close(). Preserve and pass through the third start_response argument, then test a generator response and an exception during iteration.

Trusting normalized request headers

Fix: trust only headers that a known proxy strips and rewrites, and constrain the trusted proxy path. Derive identity from a verified authentication mechanism. For auditing, log both the direct peer and the client address produced by the explicit proxy policy.

Replacing an error response after sending begins

Fix: finish failure-prone validation and authorization before committing response headers. After an exception, use exc_info so the server can enforce its already-sent decision, and accept that a committed response can only be terminated and cleaned up rather than replaced with a complete new response.

Further reading

• PEP 3333: Python Web Server Gateway Interface v1.0.1
• Python 3.14 documentation: wsgiref
• Python 3.14 documentation: wsgiref.validate
• Flask documentation: deploying to production