README.rst
1======
2Bleach
3======
4
5.. image:: https://travis-ci.org/mozilla/bleach.svg?branch=master
6 :target: https://travis-ci.org/mozilla/bleach
7
8.. image:: https://badge.fury.io/py/bleach.svg
9 :target: http://badge.fury.io/py/bleach
10
11Bleach is an allowed-list-based HTML sanitizing library that escapes or strips
12markup and attributes.
13
14Bleach can also linkify text safely, applying filters that Django's ``urlize``
15filter cannot, and optionally setting ``rel`` attributes, even on links already
16in the text.
17
18Bleach is intended for sanitizing text from *untrusted* sources. If you find
19yourself jumping through hoops to allow your site administrators to do lots of
20things, you're probably outside the use cases. Either trust those users, or
21don't.
22
23Because it relies on html5lib_, Bleach is as good as modern browsers at dealing
24with weird, quirky HTML fragments. And *any* of Bleach's methods will fix
25unbalanced or mis-nested tags.
26
27The version on GitHub_ is the most up-to-date and contains the latest bug
28fixes. You can find full documentation on `ReadTheDocs`_.
29
30:Code: https://github.com/mozilla/bleach
31:Documentation: https://bleach.readthedocs.io/
32:Issue tracker: https://github.com/mozilla/bleach/issues
33:License: Apache License v2; see LICENSE file
34
35
36Reporting Bugs
37==============
38
39For regular bugs, please report them `in our issue tracker
40<https://github.com/mozilla/bleach/issues>`_.
41
42If you believe that you've found a security vulnerability, please `file a secure
43bug report in our bug tracker
44<https://bugzilla.mozilla.org/enter_bug.cgi?assigned_to=nobody%40mozilla.org&product=Webtools&component=Bleach-security&groups=webtools-security>`_
45or send an email to *security AT mozilla DOT org*.
46
47For more information on security-related bug disclosure and the PGP key to use
48for sending encrypted mail or to verify responses received from that address,
49please read our wiki page at
50`<https://www.mozilla.org/en-US/security/#For_Developers>`_.
51
52
53Security
54========
55
56Bleach is a security-focused library.
57
58We have a responsible security vulnerability reporting process. Please use
59that if you're reporting a security issue.
60
61Security issues are fixed in private. After we land such a fix, we'll do a
62release.
63
64For every release, we mark security issues we've fixed in the ``CHANGES`` in
65the **Security issues** section. We include any relevant CVE links.
66
67
68Installing Bleach
69=================
70
71Bleach is available on PyPI_, so you can install it with ``pip``::
72
73 $ pip install bleach
74
75
76Upgrading Bleach
77================
78
79.. warning::
80
81 Before doing any upgrades, read through `Bleach Changes
82 <https://bleach.readthedocs.io/en/latest/changes.html>`_ for backwards
83 incompatible changes, newer versions, etc.
84
85
86Basic use
87=========
88
89The simplest way to use Bleach is:
90
91.. code-block:: python
92
93 >>> import bleach
94
95 >>> bleach.clean('an <script>evil()</script> example')
96 u'an <script>evil()</script> example'
97
98 >>> bleach.linkify('an http://example.com url')
99 u'an <a href="http://example.com" rel="nofollow">http://example.com</a> url'
100
101
102Code of Conduct
103===============
104
105This project and repository is governed by Mozilla's code of conduct and
106etiquette guidelines. For more details please see the `CODE_OF_CONDUCT.md
107</CODE_OF_CONDUCT.md>`_
108
109
110.. _html5lib: https://github.com/html5lib/html5lib-python
111.. _GitHub: https://github.com/mozilla/bleach
112.. _ReadTheDocs: https://bleach.readthedocs.io/
113.. _PyPI: https://pypi.org/project/bleach/
114
