docutils.transforms package

This package contains modules for standard tree transforms available to Docutils components. Tree transforms serve a variety of purposes:

• To tie up certain syntax-specific “loose ends” that remain after the initial parsing of the input plaintext. These transforms are used to supplement a limited syntax.

• To automate the internal linking of the document tree (hyperlink references, footnote references, etc.).

• To extract useful information from the document tree. These transforms may be used to construct (for example) indexes and tables of contents.

Each transform is an optional step that a Docutils component may choose to perform on the parsed document.

exception TransformError

Bases: ApplicationError

class Transform(document, startnode=None)

Bases: object

Docutils transform component abstract base class.

default_priority = None

Numerical priority of this transform, 0 through 999 (override).

__init__(document, startnode=None)

Initial setup for in-place document transforms.

document

The document tree to transform.

startnode

Node from which to begin the transform. For many transforms which apply to the document as a whole, startnode is not set (i.e. its value is None).

language

Language module local to this document.

apply(**kwargs)

Override to apply the transform to the document tree.

class Transformer(document)

Bases: TransformSpec

Store “transforms” and apply them to the document tree.

Collect lists of Transform instances and “unknown_reference_resolvers” from Docutils components (TransformSpec instances). Apply collected “transforms” to the document tree.

Also keeps track of components by component type name.

https://docutils.sourceforge.io/docs/peps/pep-0258.html#transformer

transforms

List of transforms to apply. Each item is a 4-tuple: (priority string, transform class, pending node or None, kwargs).

document

The nodes.document object this Transformer is attached to.

applied

Transforms already applied, in order.

sorted

is self.tranforms sorted?

Type:

Boolean

components

Mapping of component type name to component object.

Set by self.populate_from_components().

serialno

Internal serial number to keep track of the add order of transforms.

add_transform(transform_class, priority=None, **kwargs)

Store a single transform. Use priority to override the default. kwargs is a dictionary whose contents are passed as keyword arguments to the apply method of the transform. This can be used to pass application-specific data to the transform instance.

add_transforms(transform_list)

Store multiple transforms, with default priorities.

add_pending(pending, priority=None)

Store a transform with an associated pending node.

get_priority_string(priority)

Return a string, priority combined with self.serialno.

This ensures FIFO order on transforms with identical priority.

populate_from_components(components)

Store each component’s default transforms and reference resolvers

Transforms are stored with default priorities for later sorting. “Unknown reference resolvers” are sorted and stored. Components that don’t inherit from TransformSpec are ignored.

Also, store components by type name in a mapping for later lookup.

apply_transforms()

Apply all of the stored transforms, in priority order.

Submodules

• docutils.transforms.components module
• docutils.transforms.frontmatter module
• docutils.transforms.misc module
• docutils.transforms.parts module
• docutils.transforms.peps module
• docutils.transforms.references module
• docutils.transforms.universal module
• docutils.transforms.writer_aux module