Skip to main content

Easily use bleach with Django models and templates

Project description

Latest Version Downloads License

Bleach is a Python module that takes any HTML input, and returns valid, sanitised HTML that contains only an allowed subset of HTML tags, attributes and styles. django-bleach is a Django app that makes using bleach extremely easy.

Setup

  1. Install django-bleach via pip:

    pip install django-bleach
  2. Add django-bleach to your INSTALLED_APPS:

    INSTALLED_APPS = [
        # ...
        'django_bleach',
        # ...
    ]
  3. Select some sensible defaults for the allowed tags, attributes and styles; and the behaviour when unknown tags are encountered. Each of these are optional, and default to using the bleach defaults. See the bleach documentation:

    # Which HTML tags are allowed
    BLEACH_ALLOWED_TAGS = ['p', 'b', 'i', 'u', 'em', 'strong', 'a']
    
    # Which HTML attributes are allowed
    BLEACH_ALLOWED_ATTRIBUTES = ['href', 'title', 'style']
    
    # Which CSS properties are allowed in 'style' attributes (assuming
    # style is an allowed attribute)
    BLEACH_ALLOWED_STYLES = [
        'font-family', 'font-weight', 'text-decoration', 'font-variant']
    
    # Strip unknown tags if True, replace with HTML escaped characters if
    # False
    BLEACH_STRIP_TAGS = True
    
    # Strip comments, or leave them in.
    BLEACH_STRIP_COMMENTS = False
  4. Select the default widget for bleach fields. This defaults to django.forms.Textarea, but you will probably want to replace it with a WYSIWYG editor, or something similar:

    # Use the CKEditorWidget for bleached HTML fields
       BLEACH_DEFAULT_WIDGET = 'wysiwyg.widgets.WysiwygWidget'

    I use django-ckeditor in my projects, but what you use is up to you.

Usage

In your models

django-bleach provides three ways of creating bleached output. The simplest way of including user-editable HTML content that is automatically sanitised is by using the BleachField model field:

# in app/models.py

from django import models
from django_bleach.models import BleachField

class Post(models.Model):

    title = models.CharField()
    content = BleachField()

    # ...

BleachField takes the following arguments, to customise the output of bleach. See the bleach documentation for their use:

  • allowed_tags

  • allowed_attributes

  • allowed_styles

  • strip_tags

  • strip_comments

In addition to the bleach-specific arguments, the BleachField model field accepts all of the normal field attributes. Behind the scenes, it is a TextField, and accepts all the same arguments as the default TextField does.

The BleachField model field makes use of the BleachField form field to do all of the work. It provides no sanitisation facilities itself. This is considered a bug, but a clean solution has not yet been implemented. Any pull requests fixing this will be gratefully applied. As long as the BleachField model field is only used with BleachField form fields, there will be no problem. If this is not the case, sanitised HTML can not be guaranteed.

In your forms

A BleachField form field is provided. This field sanitises HTML input from the user, and presents safe, clean HTML to your Django application. This is where most of the work is done.

In your templates

If you have a piece of content from somewhere that needs to be printed in a template, you can use the bleach filter:

{% load bleach_tags %}

{{ some_unsafe_content|bleach }}

If filter has no arguments it uses default settings defined in your application settings. You can override allowed tags by specifying them as a parameter to the filter:

{{ some_unsafe_content|bleach:"p,span" }}

There is also bleach_linkify which uses the linkify function of bleach which converts URL-like strings in an HTML fragment to links

This function converts strings that look like URLs, domain names and email addresses in text that may be an HTML fragment to links, while preserving:

  1. links already in the string

  2. urls found in attributes

  3. email addresses

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-bleach-0.4.1.tar.gz (5.2 kB view details)

Uploaded Source

Built Distribution

django_bleach-0.4.1-py3-none-any.whl (7.2 kB view details)

Uploaded Python 3

File details

Details for the file django-bleach-0.4.1.tar.gz.

File metadata

  • Download URL: django-bleach-0.4.1.tar.gz
  • Upload date:
  • Size: 5.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.19.1 setuptools/40.6.3 requests-toolbelt/0.8.0 tqdm/4.26.0 CPython/3.7.0

File hashes

Hashes for django-bleach-0.4.1.tar.gz
Algorithm Hash digest
SHA256 8d472f1e8c68f2a7b146c3f79e226e5a5bfcaef1395cf8e10d8dbe3ca9ca1f9e
MD5 7b2bc80b4e7f63a59cdc8e0c290730f7
BLAKE2b-256 3ac3da630aba4f70aa558e3992026389bddd53c48c3e07fd3d5cec8e02a92e1a

See more details on using hashes here.

Provenance

File details

Details for the file django_bleach-0.4.1-py3-none-any.whl.

File metadata

  • Download URL: django_bleach-0.4.1-py3-none-any.whl
  • Upload date:
  • Size: 7.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.19.1 setuptools/40.6.3 requests-toolbelt/0.8.0 tqdm/4.26.0 CPython/3.7.0

File hashes

Hashes for django_bleach-0.4.1-py3-none-any.whl
Algorithm Hash digest
SHA256 c34a5b0b36c457ebeeb4ae991a40e9f70c871831ca7738a8c1e1adc8266b3853
MD5 0fc4b05f56b9fc51e7aa4e6d391278c5
BLAKE2b-256 904270980b7abb6e4c4b28396dea42d1364b172d34b1db69641ec360ef74246a

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page