#######
Clean
#######
.. module:: turbohtml.clean
Clean untrusted or raw HTML: sanitize it against an allowlist and rewrite bare URLs into links. Sanitizing is a
successor to ``bleach.clean`` -- build a :class:`Policy` (or take a preset), then sanitize; a non-overridable baseline
removes scripting elements, event-handler attributes, and ``javascript:`` URLs regardless of the policy. Linkifying is a
successor to `bleach.linkify `_ -- it finds URLs and email addresses and wraps them
in ```` links, HTML-aware so it never links inside an existing ````, a raw-text element, or a caller's
``skip_tags``.
.. autofunction:: sanitize
.. autoclass:: Sanitizer
:members: sanitize
.. autoclass:: Policy
:members: strict, basic, relaxed
.. autoclass:: OnDisallowed
:members:
The sanitizer ships bleach's default allowlists as module constants, so a :class:`Policy` can extend a known baseline
instead of enumerating a safe set from scratch.
.. autodata:: DEFAULT_TAGS
:no-value:
The tags the default policy keeps: ``a``, ``abbr``, ``acronym``, ``b``, ``blockquote``, ``code``, ``em``, ``i``,
``li``, ``ol``, ``strong``, ``ul``.
.. autodata:: DEFAULT_ATTRIBUTES
:no-value:
The attributes the default policy keeps, keyed by tag: ``href`` and ``title`` on ``a``, and ``title`` on ``abbr``
and ``acronym``.
.. autodata:: DEFAULT_SCHEMES
:no-value:
The URL schemes the default policy allows in an ``href`` or ``src``: ``http``, ``https``, ``mailto``.
.. autodata:: DEFAULT_CSS_PROPERTIES
:no-value:
The CSS properties the default policy keeps when scrubbing a ``style`` attribute: the CSS 2.1 safe set plus the SVG
paint properties.
************
Linkifying
************
A :class:`Linkify` configuration object carries the knobs: a callback receives each generated :class:`LinkCandidate` and
returns it to keep the link or ``None`` to leave the text bare, ``process_existing`` runs the callbacks over ````
tags already in the input (a callback reads ``LinkCandidate.existing`` to tell the two apart), ``extra_tlds`` extends
bare-domain detection beyond the built-in IANA table, and ``schemes`` sets which explicit-scheme URLs autolink
(defaulting to the built-in ``http``/``https``/``ftp`` set, so a typo scheme or a ``javascript://`` payload stays plain
text).
.. autofunction:: linkify
.. autoclass:: Linkify
:members:
.. autoclass:: Linker
:members: linkify
.. autoclass:: LinkCandidate
.. autofunction:: nofollow
.. autofunction:: target_blank
.. autodata:: Callback
:no-value:
The type of a linkify callback: a callable that takes one :class:`LinkCandidate` and returns it to keep the link or
``None`` to leave the text bare. :func:`nofollow` and :func:`target_blank` are built-in examples.
.. autodata:: DEFAULT_CALLBACKS
:no-value:
The callbacks :func:`linkify` applies when the caller passes none: ``(nofollow,)``, so bare-URL links get
``rel="nofollow"`` unless you opt out.
To only *locate* links in plain text rather than rewrite HTML, use :class:`LinkDetector`. It returns a :class:`LinkSpan`
for each match and accepts custom ``tlds`` and scheme-less ``schemes``.
.. autoclass:: LinkDetector
:members: find, has_link
.. autoclass:: LinkSpan
:members:
***********
Minifying
***********
:func:`minify` shrinks an HTML document in one call -- it parses the input and serializes it through the round-trip-safe
:class:`~turbohtml.Minify` layout, so the output reparses to the same tree and minifying is idempotent
(``minify(minify(x)) == minify(x)``). It replaces ``minify-html`` and ``htmlmin``. The four transforms (fold
insignificant whitespace, omit optional tags, unquote attributes, strip comments) default on; pass a
:class:`~turbohtml.Minify` to turn any off.
.. autofunction:: minify
The HTML minify layout emits ``