{"id":2343,"library":"types-webencodings","title":"Typing Stubs for webencodings","description":"types-webencodings provides static type annotations (stubs) for the 'webencodings' library. Maintained by the Typeshed project, it enables type checkers like Mypy and Pyright to perform static analysis, type inference, and provide autocompletion for code that uses 'webencodings'. These stub packages are automatically released by Typeshed's internal machinery, typically up to once a day, to keep pace with changes in the runtime libraries.","status":"active","version":"0.5.0.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","type-checking","web"],"install":[{"cmd":"pip install types-webencodings","lang":"bash","label":"Install types-webencodings"}],"dependencies":[{"reason":"This is a stub-only package; the 'webencodings' library is required at runtime for actual functionality.","package":"webencodings","optional":false}],"imports":[{"note":"Stub packages like 'types-webencodings' are not meant for direct import at runtime. They provide type information for static analysis tools for the corresponding runtime library ('webencodings').","wrong":"from types_webencodings import lookup","symbol":"lookup","correct":"from webencodings import lookup"},{"note":"Similar to functions, type checkers will find the 'Encoding' type hint via the 'webencodings' import and the installed stub package.","symbol":"Encoding","correct":"from webencodings import Encoding"}],"quickstart":{"code":"import sys\nfrom webencodings import lookup, Encoding\n\ndef get_encoding_name(label: str) -> str | None:\n    \"\"\"Looks up an encoding label and returns its canonical name, if found.\"\"\"\n    encoding: Encoding | None = lookup(label)\n    if encoding:\n        return encoding.name\n    return None\n\nif __name__ == \"__main__\":\n    # Example usage\n    utf8_name = get_encoding_name(\"utf-8\")\n    print(f\"'utf-8' canonical name: {utf8_name}\")\n\n    unknown_name = get_encoding_name(\"not-an-encoding\")\n    print(f\"'not-an-encoding' canonical name: {unknown_name}\")\n\n    # To type-check this code, save it as `main.py` and run:\n    # pip install mypy webencodings types-webencodings\n    # mypy main.py","lang":"python","description":"This example demonstrates how to use the 'webencodings' library with type hints. After installing both `webencodings` and `types-webencodings`, a type checker like Mypy will use the stubs to validate the type annotations in the code. The `lookup` function and `Encoding` type are imported directly from `webencodings`, not `types_webencodings`."},"warnings":[{"fix":"Always install `webencodings` alongside `types-webencodings` if your application uses 'webencodings' at runtime: `pip install webencodings types-webencodings`.","message":"Installing `types-webencodings` does not provide the runtime functionality of the `webencodings` library. It only provides type stubs for static analysis. You must install `webencodings` separately if you intend to run the code.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Import all symbols from the runtime package: `from webencodings import ...`.","message":"Do not attempt to import symbols directly from `types_webencodings` (e.g., `from types_webencodings import lookup`). Type stub packages are not designed to be imported at runtime. Imports should always target the actual runtime library, `webencodings`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consider pinning the `types-webencodings` version to match the major and minor version of your `webencodings` dependency (e.g., `webencodings==0.5.1` and `types-webencodings==0.5.*`). Alternatively, manage stub versions carefully to avoid unexpected type-checking errors with new runtime library releases.","message":"The versioning scheme for `types-*` packages from Typeshed is `X.Y.Z.YYYYMMDD`. The `X.Y.Z` typically corresponds to the version of the runtime package (`webencodings`) the stubs are targeting, while `YYYYMMDD` indicates the release date of the stub package from Typeshed. Incompatibility can occur if the stub package version `X.Y.Z` significantly diverges from your installed `webencodings` version.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Run your type checker (e.g., Mypy, Pyright) as part of your CI/CD pipeline and review any new type errors when updating `types-webencodings`. Pinning stub versions (`types-webencodings==X.Y.Z.YYYYMMDD`) can prevent unexpected type errors but may mean missing out on improved type fidelity.","message":"While Typeshed aims to minimize breaking changes, any update to a stub package can introduce changes that might cause your code to fail type checking, even if the runtime behavior of 'webencodings' hasn't changed. This is inherent to the nature of static typing.","severity":"breaking","affected_versions":"All versions, particularly when updating to new `types-webencodings` releases."}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}