Typing Stubs for webencodings

Warnings

• gotcha 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.
  Fix: Always install `webencodings` alongside `types-webencodings` if your application uses 'webencodings' at runtime: `pip install webencodings types-webencodings`.
• gotcha 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`.
  Fix: Import all symbols from the runtime package: `from webencodings import ...`.
• gotcha 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.
  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.
• breaking 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.
  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.

Install

• pip install types-webencodings Install types-webencodings

Imports

• lookup

  from webencodings import lookup

  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').
• Encoding

  from webencodings import Encoding

  Similar to functions, type checkers will find the 'Encoding' type hint via the 'webencodings' import and the installed stub package.

Quickstart

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`.

import sys
from webencodings import lookup, Encoding

def get_encoding_name(label: str) -> str | None:
    """Looks up an encoding label and returns its canonical name, if found."""
    encoding: Encoding | None = lookup(label)
    if encoding:
        return encoding.name
    return None

if __name__ == "__main__":
    # Example usage
    utf8_name = get_encoding_name("utf-8")
    print(f"'utf-8' canonical name: {utf8_name}")

    unknown_name = get_encoding_name("not-an-encoding")
    print(f"'not-an-encoding' canonical name: {unknown_name}")

    # To type-check this code, save it as `main.py` and run:
    # pip install mypy webencodings types-webencodings
    # mypy main.py