django_tidyfields 0.1.1

Easily accept html input with Django models, templates and DRF serializers

Version:

0.1.1

Source:

https://gitlab.routh.io/open-source/python/django-tidyfields

Keywords:

django lxml input html fields

PythonVersion:

3.6+

Sanitise HTML input from API Endpoints or Views

Contents

• 1 Features

• 2 Installation

  • 2.1 Requirements

  • 2.2 Install

  • 2.3 Configure

• 3 Usage

• 4 Advanced Usage

  • 4.1 An Additive example

1 Features

• Leverages the power of lxml to filter model fields

• Supports input from any source as the filtering is triggered by model save

2 Installation

2.1 Requirements

• Python 3.6 or above

• setuptools 30.3.0 or above

• Django 2.0 or above

2.2 Install

Install django_tidyfields via pip:

pip install django-tidyfields

Add Django TidyFields to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    'django_tidyfields',
    # ...
]

2.3 Configure

These fields pass the expected arguments for lxml.html.clean.Cleaner class through to the Cleaner instance directly. We will try to keep the docs in line with the latest integrated lxml version, however these parameters are subject to change based on the development of lxml. More on https://lxml.de

3 Usage

Django TidyFields subclass the Django TextField and CharField classes, and take any parameters available to them.

You can optionally configure the field globally in your Django Settings:

"""
Empty dict example, showing all parameters available, at their defaults.
"""
TIDYFIELDS = {
    'processing_instructions': True,
    'javascript': True,
    'comments': True,
    'style': True,
    'allow_tags': [],
    'remove_unknown_tags': False,
    'kill_tags': ['script', 'style'],
    'safe_attrs_only': True,
    'safe_attrs': [],
    'add_nofollow': True,
    'scripts': True,
    'inline_style': None,
    'links': True,
    'meta': True,
    'page_structure': True,
    'embedded': True,
    'frames': True,
    'forms': True,
    'annoying_tags': True,
    'remove_tags': None,
    'host_whitelist': [],
    'whitelist_tags': {}
}

And you can override specific parameters for each model that uses Django TidyFields. Parameters not set here will inherit from the global settings or from lxml.html.clean.Cleaner itself. Review the lxml documentation for the bleach default arguments.

models.py:

"""
A minimal Models.py usage example
"""

from django.db.models import Model
from django_tidyfields.fields import TidyTextField, TidyCharField

class UserSubmission(Model):
    title = TidyCharField()
    description = TidyTextField()
    body = TidyTextField()

4 Advanced Usage

Django TidyFields can be used however you like, but we recommend that your global defaults be a minimum allowed set of tags, or simply be setup to strip everything. If your project only allows HTML tags in certain TextFields for example, it implies that you’ll have a number of CharFields and TextFields where you want HTML to be stripped out.

You can define allowed tags when defining a field directly in the model, however you may also define addition defaults with unique variable names in your Django Settings, and use that var on any TextField that allows those tags. The fields check to see if any arguments are set in the field_args parameter, and only overrides the default arguments if you’ve passed the same argument again. So you can use additive and subtractive magic to simplify your code as much as possible. Just remember the Wizards Second Rule! (Especially when using subtractive magic)

“The Second Rule is that the greatest harm can result from the best intentions. It sounds a paradox, but kindness and good intentions can be an insidious path to destruction. Sometimes doing what seems right is wrong and can cause harm. The only counter to it is knowledge, wisdom, forethought, and understanding the First Rule. Even then, that is not always enough.”

– Zedd Zu’l Zorander

Stone of Tears, Terry Goodkind

4.1 An Additive example

settings.py:

"""
Default dict that strips all HTML, with a permissive dict for certain fields.
"""
TIDYFIELDS = {
    'processing_instructions': True,
    'javascript': True,
    'comments': True,
    'style': True,
    'allow_tags': [''],
    'remove_unknown_tags': False,
    'kill_tags': ['script', 'style'],
    'safe_attrs_only': True,
    'safe_attrs': [''],
    'add_nofollow': True
}

PERMISSIVE_TIDYFIELDS = {
    'allow_tags': ['b', 'em', 'i', 'strong', 'span', 'p', 'pagebreak'],
    'safe_attrs': ['style'],
    'style': False
}

models.py:

"""
A models.py usage example with Additive magic
"""

from django.db.models import Model
from django.conf import settings
from django_tidyfields.fields import TidyTextField, TidyCharField

class UserSubmission(Model):
    title = TidyCharField()
    description = TidyTextField()
    body = TidyTextField(field_args=settings.PERMISSIVE_TIDYFIELDS)