{"id":3836,"library":"types-bleach","title":"Typing Stubs for Bleach","description":"types-bleach provides static type checking stubs for the 'bleach' HTML sanitizing library. It enables type checkers like MyPy or Pyright to validate usage of `bleach` functions and classes without providing any runtime functionality itself. As part of typeshed, these packages are automatically released, potentially up to once a day, reflecting updates to the underlying library's API or improvements in type accuracy.","status":"active","version":"6.3.0.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","type-hints","bleach","typeshed"],"install":[{"cmd":"pip install types-bleach","lang":"bash","label":"Install types-bleach"},{"cmd":"pip install bleach types-bleach","lang":"bash","label":"Install Bleach and its stubs"}],"dependencies":[{"reason":"types-bleach provides type hints for the 'bleach' library, so 'bleach' itself is required for runtime functionality.","package":"bleach","optional":false}],"imports":[{"note":"Type stubs are not meant for runtime import; import directly from the 'bleach' library.","wrong":"from types_bleach import clean","symbol":"clean","correct":"from bleach import clean"},{"note":"Type stubs are not meant for runtime import; import directly from the 'bleach' library.","wrong":"from types_bleach import linkify","symbol":"linkify","correct":"from bleach import linkify"}],"quickstart":{"code":"import bleach\n\n# Example usage of bleach with type hints\ndef process_html(user_input: str) -> str:\n    allowed_tags = ['a', 'p', 'b', 'i']\n    allowed_attrs = {'a': ['href', 'title']}\n    \n    # The type checker will use types-bleach stubs to validate this call\n    cleaned_html: str = bleach.clean(\n        user_input,\n        tags=allowed_tags,\n        attributes=allowed_attrs,\n        strip=True\n    )\n    return cleaned_html\n\nhtml_input = '<p>Hello, <script>alert(\"XSS!\");</script><a href=\"http://example.com\">world</a>!</p>'\noutput = process_html(html_input)\nprint(output)\n# Expected output with type checking: <p>Hello, <a href=\"http://example.com\">world</a>!</p>","lang":"python","description":"This quickstart demonstrates how to use the 'bleach' library. When 'types-bleach' is installed, a static type checker will use its stubs to provide type validation and autocompletion for `bleach` functions like `clean()` and `linkify()`."},"warnings":[{"fix":"Ensure 'bleach' is installed alongside 'types-bleach' (e.g., `pip install bleach types-bleach`). Do not attempt to import modules directly from `types_bleach` at runtime.","message":"types-bleach is a stub-only package. It provides type annotations for the 'bleach' library and does not contain any executable code. You must install the 'bleach' library itself for runtime functionality.","severity":"gotcha","affected_versions":"All versions"},{"fix":"It is recommended to pin the version of `types-bleach` to match the major.minor version of your installed `bleach` library, e.g., if `bleach==6.3.0`, use `types-bleach==6.3.0.*`. Additionally, you might consider pinning the full stub version (e.g., `types-bleach==6.3.0.20260408`) if strict type-checking stability is required.","message":"Type stubs from typeshed (including types-bleach) can introduce changes that might cause your code to fail type-checking, even if the runtime library ('bleach') has not changed its API. This can occur with minor stub version bumps.","severity":"breaking","affected_versions":"All versions"},{"fix":"When specifying dependencies, understand that `types-bleach==6.3.0.20260408` means stubs for `bleach` version `6.3.0` released on April 8, 2026. This versioning helps in aligning stubs with the core library version.","message":"The versioning scheme for typeshed stub packages like `types-bleach` is `X.Y.Z.YYYYMMDD`. The `X.Y.Z` part corresponds to the version of the runtime package ('bleach') that the stubs are targeted against and tested with. The `YYYYMMDD` suffix indicates the date the stub package was published on PyPI.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}