Improve the cleanify implementation

- Add docs
- Update dependencies
- Add extras_require config
- Remove the linkify call as it's kind of unexpected behavior of this function

CHANGES.rst

@@ -11,7 +11,7 @@ Release date: -
 
 Release date: N/A
 
-- Add ``cleanify`` function to ``flask_ckeditor.utils`` for HTML sanity.
+- Add ``cleanify`` function to ``flask_ckeditor.utils`` for HTML sanitization.
 
 
 0.5.1

docs/api.rst

@@ -30,3 +30,4 @@ Utils
 
 .. autofunction:: get_url
 .. autofunction:: random_filename
+.. autofunction:: cleanify

docs/basic.rst

@@ -62,7 +62,7 @@ to True to use built-in resources. You can use ``custom_url`` to load your custo
 CKEditor provides five types of preset (see `comparison table <https://ckeditor.com/cke4/presets-all>`_ for the differences):
 
 - ``basic``
-- ``standard`` （default value）
+- ``standard`` (default value)
 - ``full``
 - ``standard-all`` (only available from CDN)
 - ``full-all`` (only available from CDN)
@@ -100,7 +100,7 @@ It's quite simple, just call ``ckeditor.create()`` in the template:
        <input type="submit">
    </form>
 
-You can use ``value`` parameter to pass preset value (i.e. ``ckeditor.create(value='blah...blah...')``.
+You can use ``value`` parameter to pass preset value (i.e. ``ckeditor.create(value='blah...blah...')``).
 
 Get the Data
 ------------
@@ -119,6 +119,31 @@ from ``request.form`` by passing ``ckeditor`` as key:
 
         return render_template('index.html')
 
+Clean the Data
+--------------
+
+It's recommended to sanitize the HTML input from user before saving it to the database.
+
+The Flask-CKEditor provides a helper function `cleanify`. To use it, install the extra dependencies:
+
+.. code-block:: bash
+
+   $ pip install flask-ckeditor[all]
+
+Then call it for your form data (you could use ``allowed_tags`` to pass a list of custom allowed HTML tags):
+
+.. code-block:: python
+
+    from flask import request, render_template
+    from flask_ckeditor.utils import cleanify
+
+    @app.route('/write')
+    def new_post():
+        if request.method == 'POST':
+            data = cleanify(request.form.get('ckeditor'))  # <--
+
+        return render_template('index.html')
+
 Working with Flask-WTF/WTForms
 -------------------------------
 

flask_ckeditor/utils.py

@@ -31,5 +31,5 @@ def cleanify(text, *, allow_tags=None):
     """
     default_allowed_tags = {'a', 'abbr', 'b', 'blockquote', 'code',
                             'em', 'i', 'li', 'ol', 'pre', 'strong', 'ul',
-                            'h1', 'h2', 'h3', 'h4', 'h5', 'p'}
-    return bleach.linkify(bleach.clean(text, tags=allow_tags or default_allowed_tags))
+                            'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p'}
+    return bleach.clean(text, tags=allow_tags or default_allowed_tags)

requirements/dev.txt

@@ -164,7 +164,7 @@ wtforms==3.1.1
     # via
     #   flask-admin
     #   flask-wtf
-bleach==6.1.0
+
 # The following packages are considered to be unsafe in a requirements file:
 # pip
 # setuptools

requirements/tests.txt

@@ -6,14 +6,16 @@
 #
 --index-url https://pypi.tuna.tsinghua.edu.cn/simple
 
+bleach==6.1.0
+    # via -r requirements/tests.in
 blinker==1.7.0
     # via flask
 click==8.1.7
     # via flask
 coverage[toml]==7.3.2
-    # via
-    #   coverage
-    #   pytest-cov
+    # via pytest-cov
+exceptiongroup==1.2.0
+    # via pytest
 flask==3.0.0
     # via
     #   -r requirements/tests.in
@@ -26,6 +28,8 @@ flask-sqlalchemy==3.1.1
     # via -r requirements/tests.in
 flask-wtf==1.2.1
     # via -r requirements/tests.in
+greenlet==3.0.2
+    # via sqlalchemy
 iniconfig==2.0.0
     # via pytest
 itsdangerous==2.1.2
@@ -49,16 +53,23 @@ pytest==7.4.3
     #   pytest-cov
 pytest-cov==4.1.0
     # via -r requirements/tests.in
+six==1.16.0
+    # via bleach
 sqlalchemy==2.0.23
     # via flask-sqlalchemy
 tablib==3.5.0
     # via -r requirements/tests.in
+tomli==2.0.1
+    # via
+    #   coverage
+    #   pytest
 typing-extensions==4.8.0
     # via sqlalchemy
+webencodings==0.5.1
+    # via bleach
 werkzeug==3.0.1
     # via flask
 wtforms==3.1.1
     # via
     #   flask-admin
     #   flask-wtf
-bleach==6.1.0

setup.py

@@ -33,6 +33,9 @@
     install_requires=[
         'Flask'
     ],
+    extras_require={
+        'all': ['flask-wtf', 'bleach']
+    },
     classifiers=[
         'Environment :: Web Environment',
         'Intended Audience :: Developers',

test_flask_ckeditor.py

@@ -9,6 +9,8 @@
 """
 import json
 import unittest
+import sys
+import builtins
 
 from flask import Flask, render_template_string, current_app
 from flask_wtf import FlaskForm, CSRFProtect
@@ -294,12 +296,6 @@ def test_cleanify_input_js(self):
         self.assertEqual(clean_ouput,
                          u'an <script>evil()</script> example')
 
-    def test_cleanify_input_url(self):
-        input = 'abc http://example.com def'
-        clean_output = cleanify(input)
-        self.assertEqual(clean_output,
-                         u'abc <a href="http://example.com" rel="nofollow">http://example.com</a> def')
-
     def test_cleanify_by_allow_tags(self):
         input = '<b> hello <a> this is a url </a> !</b> <h1> this is h1 </h1>'
         clean_out = cleanify(input, allow_tags=['b'])
@@ -331,8 +327,6 @@ def test_cleanify_by_default_allow_tags(self):
         self.assertEqual(clean_out, input)
 
     def test_import_cleanify_without_install_bleach(self):
-        import sys
-        import builtins
         origin_import = builtins.__import__
         origin_modules = sys.modules.copy()