WSGI Types for Python

This is an attempt to bring some type safety to WSGI applications using Python's new typing features (TypedDicts, Protocols). It seems to work OK but may still be full of gaps, holes, bugs, missteps, etc. It helped bring a lot of extra safety to a couple of places that really needed it though, and seemed to remain quite stable for a couple of months.

This is implemented as a Python module, rather than MyPy stubs, as it represents a protocol things can satisfy rather than a set of types for something concrete.

This package came together during an exploration documented here: https://github.com/python/mypy/issues/7654

Define a callable application as a class:

import wsgitypes

class MyApplication(wsgitypes.Application):
    def __call__(
        self,
        environ: wsgitypes.Environ,
        start_response: wsgitypes.StartResponse,
    ) -> wsgitypes.Response:
        my_header = environ.get("REQUEST_METHOD", "")
        return []

Environ should be type-safe:

class MyApplication(wsgitypes.Application):
    def __call__(
        self,
        environ: wsgitypes.Environ,
        start_response: wsgitypes.StartResponse,
    ) -> wsgitypes.Response:
        environ["wsgi.input"] # Good
        environ["wsgi.unpot"] # BORK! MyPy will catch this.
        return []

You can define your own extensions to Environ using TypedDict inheritance, like so:

class MyEnviron(wsgitypes.Environ):
    HTTP_X_MY_HEADER: t.Optional[str]

class MyApplication(wsgitypes.Application):
    def __call__(
        self,
        environ: MyEnviron,
        start_response: wsgitypes.StartResponse,
    ) -> wsgitypes.Response:
        environ = typing.cast(MyEnviron, environ)
        environ.get("HTTP_X_MY_HEADER") # Good
        return []

Note that you need to use typing.cast to convert the incoming Environ to your derived version. An attempt was made to use a type param for Environ, but it wasn't viable (even with GVR helping!): https://github.com/python/mypy/issues/7654

MyPy types for WSGI applications

Related tags

Overview

WSGI Types for Python

Owner

Blake Williams

The mypy playground. Try mypy with your web browser.

Python classes with types validation at runtime.

👻 Phantom types for Python

Flashcards - A flash card application with 2 optional command line arguments

The official GitHub mirror of https://gitlab.com/pycqa/flake8

Utilities for refactoring imports in python-like syntax.

MonkeyType as a pytest plugin.

Code audit tool for python.

:sparkles: Surface lint errors during code review

Collection of awesome Python types, stubs, plugins, and tools to work with them.

mypy plugin to type check Kubernetes resources

An extension for flake8 that forbids some imports statements in some modules.

Flake8 Type Annotation Checking

Reference implementation of sentinels for the Python stdlib

PEP-484 typing stubs for SQLAlchemy 1.4 and SQLAlchemy 2.0

Design by contract for Python. Write bug-free code. Add a few decorators, get static analysis and tests for free.

flake8 plugin to catch useless `assert` statements

🦆 Better duck-typing with mypy-compatible extensions to Protocol

A static-analysis bot for Github

Mypy plugin and stubs for SQLAlchemy