nh3

https://nh3.readthedocs.io/en/latest/
Admin
nh3 is a Python library providing bindings to the Ammonia HTML sanitization library for secure HTML...
Tokens:9,402
Snippets:68
Trust Score:9.6
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install nh3 with pip

Source: https://nh3.readthedocs.io/en/latest/

Install the nh3 package using pip.

```bash
pip install nh3
```

--------------------------------

### nh3.is_html examples

Source: https://nh3.readthedocs.io/en/latest/

Examples of nh3.is_html: returns False for plain text and True for strings containing HTML syntax. Note that invalid HTML like '<g>' also returns True.

```python
>>> nh3.is_html("plain text")
False
>>> nh3.is_html("<p>html!</p>")
True
```

--------------------------------

### Cleaner usage example

Source: https://nh3.readthedocs.io/en/latest/

Shows how to instantiate nh3.Cleaner with tags and attributes, then clean HTML fragments. The first clean call strips a script tag, the second removes an unknown em tag but keeps its text.

```python
>>> import nh3
>>> cleaner = nh3.Cleaner(tags={"b", "i"}, attributes={})
>>> cleaner.clean("<b><i>safe</i></b><script>xss</script>")
'<b><i>safe</i></b>'
>>> cleaner.clean("<b>another</b> <em>fragment</em>")
'<b>another</b> fragment'
```

--------------------------------

### Customize allowed tags with nh3.clean()

Source: https://nh3.readthedocs.io/en/latest/

Example of using the tags parameter to only allow specific tags, here only <b>.

```python
>>> nh3.clean("<b><a href='https://example.com'>Hello</a></b>", tags={"b"})
'<b>Hello</b>'
```

--------------------------------

### nh3.clean url_relative deny and rewrite_with_base

Source: https://nh3.readthedocs.io/en/latest/

Shows how url_relative controls relative URL handling: 'deny' strips them, while ('rewrite_with_base', base) resolves them against a base URL. Both examples are shown in one snippet.

```python
>>> nh3.clean('<a href="/foo">x</a>', url_relative="deny")
'<a rel="noopener noreferrer">x</a>'
>>> nh3.clean(
...     '<a href="/foo">x</a>',
...     url_relative=("rewrite_with_base", "https://example.com"),
... )
'<a href="https://example.com/foo" rel="noopener noreferrer">x</a>'
```

--------------------------------

### nh3.escape examples

Source: https://nh3.readthedocs.io/en/latest/

Examples of nh3.escape, an alias for clean_text. It escapes input strictly, encoding every character with special meaning to the HTML parser. The examples show escaping a string and preserving a tag set.

```python
>>> import nh3
>>> nh3.escape('Robert"); abuse();//')
'Robert&quot;);&#32;abuse();&#47;&#47;'
>>> nh3.escape('<span>hello <mention>moto</mention>!</span>', tags={'mention'})
'hello <mention>moto</mention>!'
```

--------------------------------

### nh3.clean_text examples

Source: https://nh3.readthedocs.io/en/latest/

Examples of nh3.clean_text: escaping a string with special characters and preserving a specified tag set. The function escapes input rather than sanitizing HTML.

```python
>>> import nh3
>>> nh3.clean_text('Robert"); abuse();//')
'Robert&quot;);&#32;abuse();&#47;&#47;'
>>> nh3.clean_text('<span>hello <mention>moto</mention>!</span>', tags={'mention'})
'hello <mention>moto</mention>!'
```

--------------------------------

### nh3.clean with id_prefix to namespace id attributes

Source: https://nh3.readthedocs.io/en/latest/

id_prefix namespaces id attributes (which must be whitelisted) to avoid collisions with page ids. The example adds 'id' to the allowed attributes for 'b' and prefixes with 'user-content-'.

```python
>>> nh3.clean(
...     '<b id="x">hi</b>',
...     attributes={"b": {"id"}},
...     id_prefix="user-content-",
... )
'<b id="user-content-x">hi</b>'
```

--------------------------------

### nh3.clean with link_rel=None to preserve rel attribute

Source: https://nh3.readthedocs.io/en/latest/

Example of maintaining the 'rel' attribute by adding it to the allowed attributes and setting link_rel=None. The output preserves the original rel='tag'.

```python
>>> from copy import deepcopy
>>> attributes = deepcopy(nh3.ALLOWED_ATTRIBUTES)
>>> attributes["a"].add("rel")
>>> nh3.clean("<a href='https://tag.example' rel='tag'>#tag</a>",
...     link_rel=None, attributes=attributes)
'<a href="https://tag.example" rel="tag">#tag</a>'
```

--------------------------------

### nh3.clean with callable url_relative to rewrite URLs

Source: https://nh3.readthedocs.io/en/latest/

A callable passed to url_relative rewrites relative URLs; returning None would strip them. The example prepends a CDN base to the src attribute.

```python
>>> nh3.clean(
...     '<img src="/a.png">',
...     url_relative=lambda url: f"https://cdn.example.com{url}",
... )
'<img src="https://cdn.example.com/a.png">'
```

--------------------------------

### nh3.clean with attribute_filter to allow class attribute

Source: https://nh3.readthedocs.io/en/latest/

Shows how to use nh3.clean with a custom attribute_filter to allow the 'class' attribute on 'a' tags, returning 'mention' for allowed values and None to strip others. The example deep-copies nh3.ALLOWED_ATTRIBUTES and adds 'class' to the 'a' set.

```python
>>> from copy import deepcopy
>>> attributes = deepcopy(nh3.ALLOWED_ATTRIBUTES)
>>> attributes["a"].add("class")
>>> def attribute_filter(tag, attr, value):
...     if tag == "a" and attr == "class":
...         if "mention" in value.split(" "):
...             return "mention"
...         return None
...     return value
>>> nh3.clean("<a class='mention unwanted'>@foo</a>",
...     attributes=attributes,
...     attribute_filter=attribute_filter)
'<a class="mention" rel="noopener noreferrer">@foo</a>'
```

--------------------------------

### Basic usage of nh3.clean()

Source: https://nh3.readthedocs.io/en/latest/

Shows how to sanitize HTML fragments with nh3.clean(), removing unknown tags and stripping event handlers.

```python
>>> import nh3
>>> nh3.clean("<unknown>hi")
'hi'
>>> nh3.clean("<b><img src='' onerror='alert(\\'hax\\')'>XSS?</b>")
'<b><img src="">XSS?</b>'
```

--------------------------------

### nh3.clean basic usage

Source: https://nh3.readthedocs.io/en/latest/

Demonstrates the nh3.clean() function with default options. It strips unknown tags and removes event handler attributes like onerror.

```python
>>> import nh3
>>> nh3.clean("<unknown>hi")
'hi'
>>> nh3.clean("<b><img src='' onerror='alert(\'hax\')'>XSS?</b>")
'<b><img src="">XSS?</b>'
```

--------------------------------

### nh3.clean with filter_style_properties

Source: https://nh3.readthedocs.io/en/latest/

Demonstrates filtering individual style properties. First allow the style attribute, then use filter_style_properties to keep only the specified properties.

```python
>>> nh3.clean(
...     '<span style="color: red; position: fixed">text</span>',
...     attributes={"span": {"style"}},
...     filter_style_properties={"color"},
... )
'<span style="color:red">text</span>'
```

--------------------------------

### nh3.clean with tags parameter

Source: https://nh3.readthedocs.io/en/latest/

Shows how to restrict allowed tags using the tags parameter. Only the b tag is kept, while the i tag is stripped but its text content remains.

```python
>>> nh3.clean("<b><i>bold italic</i></b>", tags={"b"})
'<b>bold italic</b>'
```

--------------------------------

### Customize ALLOWED_ATTRIBUTES and clean()

Source: https://nh3.readthedocs.io/en/latest/

Shows how to deep-copy the default ALLOWED_ATTRIBUTES mapping, add a custom attribute to the 'img' tag, and pass it to clean(). The output shows the added attribute is preserved and normalized to double quotes.

```python
>>> from copy import deepcopy
>>> attributes = deepcopy(nh3.ALLOWED_ATTRIBUTES)
>>> attributes["img"].add("data-invert")
>>> nh3.clean("<img src='example.jpeg' data-invert=true>", attributes=attributes)
'<img src="example.jpeg" data-invert="true">'
```

--------------------------------

### Customize ALLOWED_URL_SCHEMES and clean()

Source: https://nh3.readthedocs.io/en/latest/

Shows how to remove a URL scheme from the default ALLOWED_URL_SCHEMES set and pass it to clean(). The output demonstrates that the removed scheme's link is stripped of its href, while the remaining scheme is preserved.

```python
>>> url_schemes = nh3.ALLOWED_URL_SCHEMES - {'tel'}
>>> nh3.clean('<a href="tel:+1">Call</a> or <a href="mailto:contact@me">email</a> me.', url_schemes=url_schemes)
'<a rel="noopener noreferrer">Call</a> or <a href="mailto:contact@me" rel="noopener noreferrer">email</a> me.'
```

--------------------------------

### nh3.Cleaner

Source: https://nh3.readthedocs.io/en/latest/

Creates a reusable sanitizer according to the given options. The Cleaner class can be instantiated with various configuration parameters to customize sanitization behavior.

```APIDOC
## nh3.Cleaner

### Description
Creates a reusable sanitizer according to the given options. The Cleaner class can be instantiated with various configuration parameters to customize sanitization behavior.

### Method
Class Constructor

### Signature
`nh3.Cleaner(tags=None, clean_content_tags=None, attributes=None, attribute_filter=None, strip_comments=True, link_rel='noopener noreferrer', generic_attribute_prefixes=None, tag_attribute_values=None, set_tag_attribute_values=None, url_schemes=None, allowed_classes=None, filter_style_properties=None, url_relative=None, id_prefix=None)`

### Parameters
- **tags** (set[str], optional) - Sets the tags that are allowed.
- **clean_content_tags** (set[str], optional) - Sets the tags whose contents will be completely removed from the output. Must be disjoint from `tags`.
- **attributes** (dict[str, set[str]], optional) - Sets the HTML attributes that are allowed on specific tags, `*` key means the attributes are allowed on any tag.
- **attribute_filter** (Callable[[str, str, str], str | None], optional) - Allows rewriting of all attributes using a callback. The callback takes name of the element, attribute and its value. Returns `None` to remove the attribute, or a value to use.
- **strip_comments** (bool) - Configures the handling of HTML comments, defaults to `True`.
- **link_rel** (str) - Configures a `rel` attribute that will be added on links, defaults to `noopener noreferrer`.
- **generic_attribute_prefixes** (set[str], optional) - Sets the prefix of attributes that are allowed on any tag.
- **tag_attribute_values** (dict[str, dict[str, set[str]]], optional) - Sets the values of HTML attributes that are allowed on specific tags.
- **set_tag_attribute_values** (dict[str, dict[str, str]], optional) - Sets the values of HTML attributes that are to be set on specific tags.
- **url_schemes** (set[str], optional) - Sets the URL schemes permitted on `href` and `src` attributes.
- **allowed_classes** (dict[str, set[str]], optional) - Sets the CSS classes that are allowed on specific tags.
- **filter_style_properties** (set[str], optional) - Only allows the specified properties in style attributes.
- **url_relative** (optional) - Not documented in the source.
- **id_prefix** (optional) - Not documented in the source.

### Request Example
```python
import nh3
cleaner = nh3.Cleaner(tags={"b"})
```

### Response
#### Success Response
Returns a Cleaner instance.

#### Response Example
```python
<nh3.Cleaner object>
```
```

--------------------------------

### nh3.clean with attributes parameter

Source: https://nh3.readthedocs.io/en/latest/

Shows how to control which attributes are kept per tag using the attributes parameter. The '*' key allows an attribute on all tags, and the 'a' key allows href on anchor tags. Note that the rel attribute is added automatically.

```python
>>> nh3.clean(
...     '<a href="/" id="link">click</a>',
...     attributes={"*": {"id"}, "a": {"href"}},
... )
'<a href="/" id="link" rel="noopener noreferrer">click</a>'
```

--------------------------------

### Customize ALLOWED_TAGS and clean()

Source: https://nh3.readthedocs.io/en/latest/

Shows how to remove a tag from the default ALLOWED_TAGS set and pass it to clean(). The output demonstrates that the removed tag is stripped from the result.

```python
>>> tags = nh3.ALLOWED_TAGS - {"b"}
>>> nh3.clean("<b><i>yeah</i></b>", tags=tags)
'<i>yeah</i>'
```

--------------------------------

### nh3.clean with clean_content_tags

Source: https://nh3.readthedocs.io/en/latest/

Demonstrates the clean_content_tags parameter, which removes both the tag and its content, unlike tags which only strips the tag.

```python
>>> nh3.clean(
...     "<script>alert('xss')</script>safe",
...     clean_content_tags={"script"},
... )
'safe'
```

--------------------------------

### nh3.Cleaner.clean

Source: https://nh3.readthedocs.io/en/latest/

Sanitizes an HTML fragment using the configured Cleaner instance. The Cleaner is configured with tags, attributes, and other options at construction time.

```APIDOC
## Cleaner.clean(html)

### Description
Sanitize an HTML fragment using the configured Cleaner instance.

### Method
clean

### Parameters
- **html** (str) - Required - Input HTML fragment.

### Returns
- Sanitized HTML fragment (str).

### Example
```python
>>> import nh3
>>> cleaner = nh3.Cleaner(tags={"b", "i"}, attributes={})
>>> cleaner.clean("<b><i>safe</i></b><script>xss</script>")
'<b><i>safe</i></b>'
>>> cleaner.clean("<b>another</b> <em>fragment</em>")
'<b>another</b> fragment'
```
```

--------------------------------

### nh3.clean()

Source: https://nh3.readthedocs.io/en/latest/

Sanitizes an HTML fragment using the default settings or custom options. Returns the cleaned HTML string.

```APIDOC
## nh3.clean()

### Description
Sanitizes an HTML fragment using the default settings or custom options. Returns the cleaned HTML string.

### Method
Function

### Signature
`nh3.clean(html, tags=None, clean_content_tags=None, attributes=None, attribute_filter=None, strip_comments=True, link_rel='noopener noreferrer', generic_attribute_prefixes=None, tag_attribute_values=None, set_tag_attribute_values=None, url_schemes=None, allowed_classes=None, filter_style_properties=None, url_relative=None, id_prefix=None)`

### Parameters
- **html** (str) - Required - The HTML fragment to sanitize.
- **tags** (set[str], optional) - Sets the tags that are allowed.
- **clean_content_tags** (set[str], optional) - Sets the tags whose contents will be completely removed from the output. Must be disjoint from `tags`.
- **attributes** (dict[str, set[str]], optional) - Sets the HTML attributes that are allowed on specific tags, `*` key means the attributes are allowed on any tag.
- **attribute_filter** (Callable[[str, str, str], str | None], optional) - Allows rewriting of all attributes using a callback. The callback takes name of the element, attribute and its value. Returns `None` to remove the attribute, or a value to use.
- **strip_comments** (bool) - Configures the handling of HTML comments, defaults to `True`.
- **link_rel** (str) - Configures a `rel` attribute that will be added on links, defaults to `noopener noreferrer`.
- **generic_attribute_prefixes** (set[str], optional) - Sets the prefix of attributes that are allowed on any tag.
- **tag_attribute_values** (dict[str, dict[str, set[str]]], optional) - Sets the values of HTML attributes that are allowed on specific tags.
- **set_tag_attribute_values** (dict[str, dict[str, str]], optional) - Sets the values of HTML attributes that are to be set on specific tags.
- **url_schemes** (set[str], optional) - Sets the URL schemes permitted on `href` and `src` attributes.
- **allowed_classes** (dict[str, set[str]], optional) - Sets the CSS classes that are allowed on specific tags.
- **filter_style_properties** (set[str], optional) - Only allows the specified properties in style attributes.
- **url_relative** (optional) - Not documented in the source.
- **id_prefix** (optional) - Not documented in the source.

### Request Example
```python
import nh3
nh3.clean("<unknown>hi")
```

### Response
#### Success Response
Returns the sanitized HTML string.

#### Response Example
```python
'hi'
```
```

--------------------------------

### nh3.clean with tag_attribute_values and set_tag_attribute_values

Source: https://nh3.readthedocs.io/en/latest/

Demonstrates tag_attribute_values to restrict attribute values and set_tag_attribute_values to unconditionally add attributes. Note that tag_attribute_values is an alternate to attributes; listing an attribute in both raises ValueError.

```python
>>> nh3.clean(
...     "<div role='alert'>warning</div>",
...     tag_attribute_values={"div": {"role": {"alert", "status"}}},
... )
'<div role="alert">warning</div>'
>>> nh3.clean(
...     "<div role='banner'>warning</div>",
...     tag_attribute_values={"div": {"role": {"alert", "status"}}},
... )
'<div>warning</div>'
>>> nh3.clean(
...     "<div>content</div>",
...     set_tag_attribute_values={"div": {"class": "safe"}},
... )
'<div class="safe">content</div>'
```

--------------------------------

### nh3.clean with allowed_classes

Source: https://nh3.readthedocs.io/en/latest/

Shows how to filter CSS class names per tag using the allowed_classes parameter. Only the specified classes are kept.

```python
>>> nh3.clean(
...     '<span class="highlight bold">text</span>',
...     allowed_classes={"span": {"highlight"}},
... )
'<span class="highlight">text</span>'
```

--------------------------------

### nh3.clean

Source: https://nh3.readthedocs.io/en/latest/

Sanitizes an HTML fragment according to the given options. This is a module-level function that accepts all sanitizer options as parameters.

```APIDOC
## nh3.clean(html, tags=None, clean_content_tags=None, attributes=None, attribute_filter=None, strip_comments=True, link_rel='noopener noreferrer', generic_attribute_prefixes=None, tag_attribute_values=None, set_tag_attribute_values=None, url_schemes=None, allowed_classes=None, filter_style_properties=None, url_relative=None, id_prefix=None)

### Description
Sanitize an HTML fragment according to the given options. See `Cleaner()` for detailed sanitizer options.

### Parameters
- **html** (str) - Required - Input HTML fragment.
- **tags** (set, optional) - Set of allowed tags. Tags not in this set are stripped but their content is kept.
- **clean_content_tags** (set, optional) - Tags whose content is also removed.
- **attributes** (dict, optional) - Mapping of tag to set of allowed attributes. Use `"*"` as a key to allow an attribute on all tags.
- **attribute_filter** (callable, optional) - Callable to filter attributes.
- **strip_comments** (bool, optional) - Whether to strip HTML comments. Defaults to `True`.
- **link_rel** (str, optional) - Value for `rel` attribute on links. Defaults to `'noopener noreferrer'`.
- **generic_attribute_prefixes** (set, optional) - Prefixes for generic attributes.
- **tag_attribute_values** (dict, optional) - Restricts an attribute to a set of allowed values. Must not overlap with `attributes`.
- **set_tag_attribute_values** (dict, optional) - Unconditionally adds attributes.
- **url_schemes** (set, optional) - Allowed URL schemes.
- **allowed_classes** (dict, optional) - Filters CSS class names per tag.
- **filter_style_properties** (set, optional) - Allowed CSS style properties.
- **url_relative** (str | tuple | callable, optional) - Configures how relative URLs are handled.
- **id_prefix** (str, optional) - Prepends a string to allowed `id` attribute values.

### Returns
- Sanitized HTML fragment (str).

### Examples
```python
>>> import nh3
>>> nh3.clean("<unknown>hi")
'hi'
>>> nh3.clean("<b><img src='' onerror='alert(\\'hax\\')'>XSS?</b>")
'<b><img src="">XSS?</b>'
>>> nh3.clean("<b><i>bold italic</i></b>", tags={"b"})
'<b>bold italic</b>'
>>> nh3.clean("<script>alert('xss')</script>safe", clean_content_tags={"script"})
'safe'
>>> nh3.clean('<a href="/" id="link">click</a>', attributes={"*": {"id"}, "a": {"href"}})
'<a href="/" id="link" rel="noopener noreferrer">click</a>'
>>> nh3.clean("<div role='alert'>warning</div>", tag_attribute_values={"div": {"role": {"alert", "status"}}})
'<div role="alert">warning</div>'
>>> nh3.clean("<div role='banner'>warning</div>", tag_attribute_values={"div": {"role": {"alert", "status"}}})
'<div>warning</div>'
>>> nh3.clean("<div>content</div>", set_tag_attribute_values={"div": {"class": "safe"}})
'<div class="safe">content</div>'
>>> nh3.clean('<span class="highlight bold">text</span>', allowed_classes={"span": {"highlight"}})
'<span class="highlight">text</span>'
>>> nh3.clean('<span style="color: red; position: fixed">text</span>', attributes={"span": {"style"}}, filter_style_properties={"color"})
'<span style="color:red">text</span>'
```
```

--------------------------------

### nh3.clean

Source: https://nh3.readthedocs.io/en/latest/

Sanitizes an HTML fragment, removing dangerous tags and attributes while allowing customization via parameters such as attributes, attribute_filter, link_rel, url_relative, and id_prefix.

```APIDOC
## nh3.clean

### Description
Sanitizes an HTML fragment, removing dangerous tags and attributes while allowing customization via parameters such as attributes, attribute_filter, link_rel, url_relative, and id_prefix.

### Method
Function

### Signature
`nh3.clean(html, tags=None, attributes=None, attribute_filter=None, link_rel=None, url_relative=None, id_prefix=None)`

### Parameters
- **html** (`str`) - Required - Input HTML fragment
- **tags** (`set[str]`, optional) - Tags to allow; defaults to `nh3.ALLOWED_TAGS`
- **attributes** (`dict`, optional) - Allowed attributes per tag; defaults to `nh3.ALLOWED_ATTRIBUTES`
- **attribute_filter** (`callable`, optional) - Callable `(tag, attr, value)` returning the value to use or `None` to remove the attribute
- **link_rel** (`str` or `None`, optional) - Value for `rel` attribute on links; `None` removes it
- **url_relative** (`str` or `tuple` or `callable`, optional) - Controls handling of relative URLs: `"deny"` strips them, `("rewrite_with_base", base)` resolves against a base URL, or a callable rewrites them (return `None` to strip)
- **id_prefix** (`str`, optional) - Prefix for `id` attributes (must be whitelisted)

### Returns
Sanitized HTML string

### Return Type
`str`

### Examples
```python
>>> from copy import deepcopy
>>> attributes = deepcopy(nh3.ALLOWED_ATTRIBUTES)
>>> attributes["a"].add("class")
>>> def attribute_filter(tag, attr, value):
...     if tag == "a" and attr == "class":
...         if "mention" in value.split(" "):
...             return "mention"
...         return None
...     return value
>>> nh3.clean("<a class='mention unwanted'>@foo</a>",
...     attributes=attributes,
...     attribute_filter=attribute_filter)
'<a class="mention" rel="noopener noreferrer">@foo</a>'
```

```python
>>> from copy import deepcopy
>>> attributes = deepcopy(nh3.ALLOWED_ATTRIBUTES)
>>> attributes["a"].add("rel")
>>> nh3.clean("<a href='https://tag.example' rel='tag'>#tag</a>",
...     link_rel=None, attributes=attributes)
'<a href="https://tag.example" rel="tag">#tag</a>'
```

```python
>>> nh3.clean('<a href="/foo">x</a>', url_relative="deny")
'<a rel="noopener noreferrer">x</a>'
>>> nh3.clean(
...     '<a href="/foo">x</a>',
...     url_relative=("rewrite_with_base", "https://example.com"),
... )
'<a href="https://example.com/foo" rel="noopener noreferrer">x</a>'
```

```python
>>> nh3.clean(
...     '<img src="/a.png">',
...     url_relative=lambda url: f"https://cdn.example.com{url}",
... )
'<img src="https://cdn.example.com/a.png">'
```

```python
>>> nh3.clean(
...     '<b id="x">hi</b>',
...     attributes={"b": {"id"}},
...     id_prefix="user-content-",
... )
'<b id="user-content-x">hi</b>'
```
```

--------------------------------

### nh3.ALLOWED_TAGS

Source: https://nh3.readthedocs.io/en/latest/

The default set of tags allowed by clean(). Useful for customizing the default to add or remove some tags.

```APIDOC
## nh3.ALLOWED_TAGS

### Description
The default set of tags allowed by `clean()`. Useful for customizing the default to add or remove some tags.

### Usage Example
```python
>>> tags = nh3.ALLOWED_TAGS - {"b"}
>>> nh3.clean("<b><i>yeah</i></b>", tags=tags)
'<i>yeah</i>'
```
```

--------------------------------

### nh3.ALLOWED_URL_SCHEMES

Source: https://nh3.readthedocs.io/en/latest/

The default set of URL schemes permitted on href and src attributes. Useful for customizing the default to add or remove some URL schemes.

```APIDOC
## nh3.ALLOWED_URL_SCHEMES

### Description
The default set of URL schemes permitted on `href` and `src` attributes. Useful for customizing the default to add or remove some URL schemes.

### Usage Example
```python
>>> url_schemes = nh3.ALLOWED_URL_SCHEMES - {'tel'}
>>> nh3.clean('<a href="tel:+1">Call</a> or <a href="mailto:contact@me">email</a> me.', url_schemes=url_schemes)
'<a rel="noopener noreferrer">Call</a> or <a href="mailto:contact@me" rel="noopener noreferrer">email</a> me.'
```
```

--------------------------------

### nh3.ALLOWED_ATTRIBUTES

Source: https://nh3.readthedocs.io/en/latest/

The default mapping of tags to allowed attributes for clean(). Useful for customizing the default to add or remove some attributes.

```APIDOC
## nh3.ALLOWED_ATTRIBUTES

### Description
The default mapping of tags to allowed attributes for `clean()`. Useful for customizing the default to add or remove some attributes.

### Usage Example
```python
>>> from copy import deepcopy
>>> attributes = deepcopy(nh3.ALLOWED_ATTRIBUTES)
>>> attributes["img"].add("data-invert")
>>> nh3.clean("<img src='example.jpeg' data-invert=true>", attributes=attributes)
'<img src="example.jpeg" data-invert="true">'
```
```

--------------------------------

### nh3.is_html

Source: https://nh3.readthedocs.io/en/latest/

Determines if a given string contains HTML by parsing the full string and checking for any HTML syntax. Returns True for strings with invalid HTML syntax like '<g>'.

```APIDOC
## nh3.is_html

### Description
Determine if a given string contains HTML. This function parses the full string and checks for any HTML syntax. Note: This function will return True for strings that contain invalid HTML syntax like `<g>` and even `Vec::<u8>::new()`.

### Method
Function

### Signature
`nh3.is_html(html)`

### Parameters
- **html** (`str`) - Required - Input string

### Returns
Boolean indicating whether the string contains HTML

### Return Type
`bool`

### Examples
```python
>>> nh3.is_html("plain text")
False
>>> nh3.is_html("<p>html!</p>")
True
```
```

--------------------------------

### nh3.clean_text

Source: https://nh3.readthedocs.io/en/latest/

Turns an arbitrary string into unformatted HTML by escaping all special characters. Optionally preserves specified tags without attributes.

```APIDOC
## nh3.clean_text

### Description
Turn an arbitrary string into unformatted HTML. Escapes input rather than sanitizing HTML. Roughly equivalent to Python's html.escape() or PHP's htmlspecialchars and htmlentities. Escaping is as strict as possible, encoding every character that has special meaning to the HTML parser.

### Method
Function

### Signature
`nh3.clean_text(html, tags=None)`

### Parameters
- **html** (`str`) - Required - Input HTML fragment
- **tags** (`set[str]`, optional) - Tags to preserve; when omitted the string is fully escaped.

### Returns
Cleaned text

### Return Type
`str`

### Examples
```python
>>> import nh3
>>> nh3.clean_text('Robert"); abuse();//')
'Robert&quot;);&#32;abuse();&#47;&#47;'
>>> nh3.clean_text('<span>hello <mention>moto</mention>!</span>', tags={'mention'})
'hello <mention>moto</mention>!'
```
```

--------------------------------

### nh3.escape

Source: https://nh3.readthedocs.io/en/latest/

HTML-escape an arbitrary string. Alias for clean_text() with the same signature and behavior. The escape name is preferred because it escapes input rather than sanitizing HTML.

```APIDOC
## nh3.escape

### Description
HTML-escape an arbitrary string. Alias for `clean_text()` — same signature, same behaviour. The `escape` name is preferred because the function escapes input rather than sanitizing HTML. Note: this is stricter than Python's stdlib `html.escape()`. `html.escape` only encodes `&`, `<`, `>`, and optionally `"` and `'`; `nh3.escape` encodes every character that has special meaning to the HTML parser.

### Method
Function

### Signature
`nh3.escape(html, tags=None)`

### Parameters
- **html** (`str`) - Required - Input HTML fragment
- **tags** (`set[str]`, optional) - Tags to preserve; when omitted the string is fully escaped.

### Returns
Escaped text

### Return Type
`str`

### Examples
```python
>>> import nh3
>>> nh3.escape('Robert"); abuse();//')
'Robert&quot;);&#32;abuse();&#47;&#47;'
>>> nh3.escape('<span>hello <mention>moto</mention>!</span>', tags={'mention'})
'hello <mention>moto</mention>!'
```
```
Tokens:
Raw