{"id":8745,"library":"types-waitress","title":"Typing Stubs for Waitress","description":"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.","status":"active","version":"3.0.1.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","waitress","typeshed","type-checking","mypy","pyright","wsgi-server"],"install":[{"cmd":"pip install types-waitress","lang":"bash","label":"Install the type stubs"},{"cmd":"pip install waitress","lang":"bash","label":"Install the runtime library (if not already installed)"}],"dependencies":[{"reason":"Provides the runtime functionality for which these stubs offer type hints. This `types-waitress` version aims to provide annotations for `waitress~=3.0.1`.","package":"waitress","optional":false},{"reason":"Minimum Python version required for the `types-waitress` package itself.","package":"python","version":">=3.10","optional":false}],"imports":[{"note":"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.","symbol":"serve","correct":"from waitress import serve"},{"note":"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.","symbol":"WSGI application components","correct":"from typing import Callable, Iterable, Dict, Any"}],"quickstart":{"code":"# app.py\nfrom wsgiref.simple_server import make_server\nfrom waitress import serve\nfrom typing import Callable, Iterable, Dict, Any\n\ndef simple_app(environ: Dict[str, Any], start_response: Callable) -> Iterable[bytes]:\n    \"\"\"A barebones WSGI application with type hints.\"\"\"\n    status = '200 OK'\n    headers = [('Content-type', 'text/plain; charset=utf-8')]\n    start_response(status, headers)\n    return [b\"Hello, Waitress with types!\"]\n\nif __name__ == '__main__':\n    print(\"Serving on http://127.0.0.1:8080\")\n    # Typical production deployment would use the command line:\n    # waitress-serve --host=127.0.0.1 --port=8080 app:simple_app\n    # For direct Python execution:\n    serve(simple_app, host='127.0.0.1', port=8080)\n\n# To type check this application:\n# 1. Ensure you have a type checker installed, e.g., pip install mypy\n# 2. Run the type checker from your terminal: mypy app.py","lang":"python","description":"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."},"warnings":[{"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`).","message":"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.","severity":"gotcha","affected_versions":"All 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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"Module \"waitress\" has no attribute \"serve\" (reportMissingModuleStubs)"},{"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]: ...`","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.","error":"Argument \"wsgi_app\" to \"serve\" has incompatible type \"...\" (expected \"Callable[[...], Iterable[bytes]]\")"},{"fix":"Install the actual `waitress` library: `pip install waitress`. The `types-waitress` package only provides type hints, not the runtime code.","cause":"The `waitress` runtime library itself is not installed in the Python environment where the code or type checker is running.","error":"Import \"waitress\" could not be resolved (reportMissingImports)"}]}