File: index.rst

package info (click to toggle)
python-nh3 0.3.0-1
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid
  • size: 220 kB
  • sloc: python: 100; makefile: 35; sh: 17
file content (73 lines) | stat: -rw-r--r-- 2,021 bytes parent folder | download
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.'