1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
|
nh3
===
Python bindings to the `ammonia <https://github.com/rust-ammonia/ammonia>`__ HTML sanitization library.
Installation
------------
.. code-block:: bash
pip install nh3
Usage
-----
Use ``clean()`` to sanitize HTML fragments:
.. code-block:: pycon
>>> import nh3
>>> nh3.clean("<unknown>hi")
'hi'
>>> nh3.clean("<b><img src='' onerror='alert(\\'hax\\')'>XSS?</b>")
'<b><img src="">XSS?</b>'
It has many options to customize the sanitization, as documented below.
For example, to only allow ``<b>`` tags:
.. code-block:: python
>>> nh3.clean("<b><a href='https://example.com'>Hello</a></b>", tags={"b"})
'<b>Hello</b>'
API reference
-------------
.. automodule:: nh3
:members:
.. attribute:: ALLOWED_TAGS
The default set of tags allowed by ``clean()``.
Useful for customizing the default to add or remove some tags:
.. code-block:: pycon
>>> tags = nh3.ALLOWED_TAGS - {"b"}
>>> nh3.clean("<b><i>yeah</i></b>", tags=tags)
'<i>yeah</i>'
.. attribute:: ALLOWED_ATTRIBUTES
The default mapping of tags to allowed attributes for ``clean()``.
Useful for customizing the default to add or remove some attributes:
.. code-block:: pycon
>>> 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">'
.. attribute:: ALLOWED_URL_SCHEMES
The default set of URL schemes permitted on ``href`` and ``src`` attributes.
Useful for customizing the default to add or remove some URL schemes:
.. code-block:: pycon
>>> 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.'
|