Typing Stubs for Bleach

6.3.0.20260408 · active · verified Sat Apr 11

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.

Warnings

gotcha 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.
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.
breaking 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.
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.
gotcha 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.
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.

Install

pip install types-bleach Install types-bleach
pip install bleach types-bleach Install Bleach and its stubs

Imports

clean
```
from bleach import clean
```
Type stubs are not meant for runtime import; import directly from the 'bleach' library.
linkify
```
from bleach import linkify
```
Type stubs are not meant for runtime import; import directly from the 'bleach' library.

Quickstart

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

import bleach

# Example usage of bleach with type hints
def process_html(user_input: str) -> str:
    allowed_tags = ['a', 'p', 'b', 'i']
    allowed_attrs = {'a': ['href', 'title']}
    
    # The type checker will use types-bleach stubs to validate this call
    cleaned_html: str = bleach.clean(
        user_input,
        tags=allowed_tags,
        attributes=allowed_attrs,
        strip=True
    )
    return cleaned_html

html_input = '<p>Hello, <script>alert("XSS!");</script><a href="http://example.com">world</a>!</p>'
output = process_html(html_input)
print(output)
# Expected output with type checking: <p>Hello, <a href="http://example.com">world</a>!</p>

view raw JSON →