Install & Compatibility
Where this runs
tested against v1.0.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.7s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
markdown_tags
✓ from bleach_allowlist import markdown_tags
markdown_attrs
✓ from bleach_allowlist import markdown_attrs
print_tags
✓ from bleach_allowlist import print_tags
print_attrs
✓ from bleach_allowlist import print_attrs
all_styles
✓ from bleach_allowlist import all_styles
standard_styles
✓ from bleach_allowlist import standard_styles
This quickstart demonstrates using `bleach-allowlist` with the `bleach` library to sanitize an HTML string. It imports predefined tag, attribute, and style lists and applies them to `bleach.clean()` for secure content rendering. Note that `bleach` itself has deprecated direct `styles` argument in favor of `css_sanitizer` in recent versions; the example above demonstrates the older usage for `styles` or illustrates the values provided.
import bleach
from bleach_allowlist import print_tags, print_attrs, all_styles
raw_html = '<h1>Hello <script>alert("XSS")</script>World!</h1><p style="color: red;">This is a paragraph.</p><a href="javascript:alert(1)">Click me</a>'
# Bleach requires the css_sanitizer for style attributes
# You might need to install 'bleach[css]' if you use advanced CSS sanitization.
# For simple use, passing all_styles works with default bleach setup for allowed styles.
# Note: bleach itself is deprecated, consider alternatives for new projects.
# If you are using bleach >= 5.0, CSS sanitization is significantly different.
# You would typically use bleach.css_sanitizer.CSSSanitizer
# For this example, assuming a version of bleach where `all_styles` can be passed directly
# or for illustration of values. Always refer to bleach's current documentation.
sanitized_html = bleach.clean(
raw_html,
tags=print_tags,
attributes=print_attrs,
styles=all_styles, # Note: For modern bleach, use css_sanitizer=CSSSanitizer(allowed_css_properties=all_styles)
strip=True
)
print(sanitized_html)
Debug
Known issues
breakingThe upstream `bleach` library, which `bleach-allowlist` depends on, has been deprecated since January 2023. While `bleach-allowlist` itself provides static lists and is not deprecated, its utility is tied directly to `bleach`.fixFor new projects, consider alternative HTML sanitization libraries. If you must use `bleach`, be aware of its maintenance status. No direct fix for `bleach-allowlist`, as it's a data provider.
affects: All versions of `bleach-allowlist` are affected by the deprecation of `bleach`.
deprecatedThe project was originally released under the name `bleach-whitelist` and subsequently renamed to `bleach-allowlist`. The `bleach-whitelist` package is deprecated and will not receive updates.fixEnsure you are installing and importing from `bleach-allowlist`.
affects: < 1.0.0 (`bleach-whitelist` package)
breakingThe `bleach` library, particularly in versions 5.0.0 and above, introduced significant breaking changes related to CSS sanitization. The `styles` argument to `bleach.clean` was removed and replaced with a `css_sanitizer` argument that expects an instance of `bleach.css_sanitizer.CSSSanitizer`.fixIf using `bleach-allowlist`'s `all_styles` or `standard_styles` with modern `bleach`, you must adapt your `bleach.clean` call. Instead of `styles=all_styles`, use `from bleach.css_sanitizer import CSSSanitizer; css_sanitizer=CSSSanitizer(allowed_css_properties=all_styles)`.
affects: `bleach` >= 5.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'bleach_whitelist'
Attempting to import from the old, deprecated package name `bleach-whitelist`.
fixThe package was renamed. Install `bleach-allowlist` and update your imports from `bleach_whitelist` to `bleach_allowlist`.
TypeError: clean() got an unexpected keyword argument 'styles'
This error occurs when using `bleach.clean()` with the `styles` keyword argument in `bleach` versions 5.0.0 or later. The API changed to use a `css_sanitizer` object instead.
fixUpgrade your `bleach.clean` call. Instead of passing `styles=...`, import `CSSSanitizer` from `bleach.css_sanitizer` and pass an instance: `css_sanitizer=CSSSanitizer(allowed_css_properties=your_style_list)`.
Upgrade
Version history
1.0.3latest on PyPI · released Aug 13, 2020
Audit
Dependencies
bleachrequiredThis library provides allowlists specifically for use with the `bleach` HTML sanitization library. It is a functional dependency.