WSGI — Understanding Python’s Web Server Interfaces

WSGI — Understanding Python’s Web Server Interfaces

WSGI

stands for Web Server Gateway Interface. It is a standard gateway interface that defines how a python web application communicates with a web server. In simple terms it defines how the server(Nginx , Apache etc) calls your Python application.

Python frameworks like Django, Flask & FastApi provide development servers only .

Client (Browser / Mobile / API client) ↓ HTTP Web Server / Reverse Proxy (Nginx, Apache) ↓ WSGI WSGI Server (Gunicorn / uWSGI / mod_wsgi) ↓ Python call Python Web App (Flask / Django) ↑ Response

What WSGI actually is?

It defines:

• How an HTTP request becomes a Python call
• How a Python app returns a response
• How environment data is passed

WSGI rule:

A Python web app must be a callable that accepts

(environ, start_response)

Step-by-step request lifecycle

1. Client sends request

GET /users?id=1 HTTP/1.1 Host: example.com

2. Web server receives it

Nginx: Accepts TCP connection Handles TLS, buffering, timeouts Forwards request to WSGI server

3. WSGI server translates HTTP → Python

Gunicorn: Parses HTTP Creates a Python dictionary called environ

Example environ:

{
  'REQUEST_METHOD': 'GET',
  'PATH_INFO': '/users',
  'QUERY_STRING': 'id=1',
  'SERVER_NAME': 'example.com',
  'SERVER_PORT': '80',
  'wsgi.version': (1, 0),
  'wsgi.input': <file-like object>,
  'wsgi.errors': <file-like object>,
}

4. WSGI server calls your app

response = app(environ, start_response)

Your Flask/Django app is just a callable.

How Flask fits into this?

When you write:

from flask import Flask
app = Flask(__name__)

Flask() creates an object of class Flask.

That class implements the __call__ method, which makes the object callable.

• Internally, __call__ is compatible with WSGI:

# Simplified pseudo-code
class Flask:
    def __call__(self, environ, start_response):
        # Convert environ to Request object
        # Route to the right view function
        # Call start_response
        # Return response iterable
        return response_iterable

5. Python app processes request

Framework:

• Reads from environ
• Routes request
• Executes business logic
• Prepares response

6. App returns response

start_response is a function provided by the WSGI server to the Python application, which the app must call to begin the HTTP response.

It tells the server:

HTTP status Response headers Headers must be sent before the body

Example:

start_response(
    "200 OK",
    [("Content-Type", "application/json")]
)
return [b'{"message": "Hello"}']

• Response body must be bytes
• Returned as an iterable

How frameworks like Flask handle this?

Flask does the encoding for you:

from flask import Flask, jsonify
app = Flask(__name__)

@app.route("/hello")
def hello():
    return jsonify({"message": "Hello Flask"})

• jsonify() converts Python dict → JSON string → UTF-8 bytes
• Flask calls start_response() and returns bytes to the WSGI server

7. WSGI server sends HTTP response

Gunicorn:

• Converts response into HTTP
• Sends it back to Nginx
• Nginx sends it to client