Typing Stubs for Waitress

3.0.1.20260408 · active · verified Thu Apr 16

This is a type stub package for the `waitress` WSGI server, providing static type annotations for use with type checkers like MyPy and Pyright. It allows developers to leverage type checking for `waitress` without modifying its runtime code. The current version is 3.0.1.20260408 and it is released as part of the `typeshed` project, with updates for third-party stubs typically occurring up to once a day.

Common errors

```
Module "waitress" has no attribute "serve" (reportMissingModuleStubs)
```
cause The `types-waitress` stub package is not installed or your type checker (e.g., MyPy, Pyright) is not correctly configured to find it in your environment.

fix Ensure `pip install types-waitress` has been run in the Python environment used by your type checker. Also, verify your type checker's configuration.
```
Argument "wsgi_app" to "serve" has incompatible type "..." (expected "Callable[[...], Iterable[bytes]]")
```
cause The WSGI application function passed to `waitress.serve` does not conform to the expected type signature as defined in the `types-waitress` stubs. For instance, `environ` or `start_response` might have incorrect type hints or return types.

fix Adjust your WSGI application's function signature to match the expected types: `def my_app(environ: Dict[str, Any], start_response: Callable) -> Iterable[bytes]: ...`
```
Import "waitress" could not be resolved (reportMissingImports)
```
cause The `waitress` runtime library itself is not installed in the Python environment where the code or type checker is running.

fix Install the actual `waitress` library: `pip install waitress`. The `types-waitress` package only provides type hints, not the runtime code.

Warnings

gotcha Type stub packages like `types-waitress` must be kept in sync with the runtime library (`waitress`) they annotate. If the `waitress` version updates significantly and `types-waitress` does not, type checking might produce false positives or miss actual errors.
Fix: Regularly update both `waitress` and `types-waitress`. Pin `types-waitress` to match the major.minor version of `waitress` (e.g., if `waitress==3.0.x`, use `types-waitress==3.0.x.YYYYMMDD`).
breaking Even minor changes within type stubs can sometimes lead to new type-checking errors, even if the underlying runtime code functions identically. This is because type checkers might become stricter or new type features are used in stubs that break compatibility with older type checker versions.
Fix: Pin your type checker (e.g., `mypy==1.19.1`) along with your stub packages if strict type checking stability is critical. Consult the `typeshed` documentation for compatibility with specific type checker versions.
gotcha The naming convention `types-<library_name>` for stub-only packages from `typeshed` means you install `types-waitress` but still import from `waitress`. New users sometimes expect to import from the stub package directly.
Fix: Always import symbols from the original runtime library (`waitress`). The type checker automatically finds and applies the type information from the installed `types-waitress` package.

Install

pip install types-waitress Install the type stubs
pip install waitress Install the runtime library (if not already installed)

Imports

serve
```
from waitress import serve
```
Type checkers (e.g., MyPy, Pyright) will automatically discover and use the installed `types-waitress` stubs for `waitress` imports. There is no direct `import types_waitress` in user code.
WSGI application components
```
from typing import Callable, Iterable, Dict, Any
```
While `types-waitress` provides stubs for `waitress` functions, standard Python `typing` module components are essential for annotating your own WSGI application correctly, which `waitress.serve` expects.

Quickstart

This quickstart demonstrates a basic WSGI application that can be served by `waitress`. After installing `waitress` and `types-waitress`, a type checker like MyPy can validate the types used in the `simple_app` and `serve` call against the provided stubs, catching potential errors at development time. The example includes the recommended type hints for a WSGI application.

# app.py
from wsgiref.simple_server import make_server
from waitress import serve
from typing import Callable, Iterable, Dict, Any

def simple_app(environ: Dict[str, Any], start_response: Callable) -> Iterable[bytes]:
    """A barebones WSGI application with type hints."""
    status = '200 OK'
    headers = [('Content-type', 'text/plain; charset=utf-8')]
    start_response(status, headers)
    return [b"Hello, Waitress with types!"]

if __name__ == '__main__':
    print("Serving on http://127.0.0.1:8080")
    # Typical production deployment would use the command line:
    # waitress-serve --host=127.0.0.1 --port=8080 app:simple_app
    # For direct Python execution:
    serve(simple_app, host='127.0.0.1', port=8080)

# To type check this application:
# 1. Ensure you have a type checker installed, e.g., pip install mypy
# 2. Run the type checker from your terminal: mypy app.py

view raw JSON →