docutils.nodes

module documentation

(source)

Docutils document tree element class library.

Classes in CamelCase are abstract base classes or auxiliary classes. The one exception is Text, for a text (PCDATA) node; uppercase is used to differentiate from element classes. Classes in lower_case_with_underscores are element classes, matching the XML element generic identifiers in the DTD.

The position of each node (the level at which it can occur) is significant and is represented by abstract base classes (Root, Structural, Body, Inline, etc.). Certain transformations will be easier because we can use isinstance(node, base_class) to determine the position of the node in the hierarchy.

Class	`abbreviation`	Undocumented
Class	`acronym`	Undocumented
Class	`address`	Undocumented
Class	`Admonition`	Undocumented
Class	`admonition`	Undocumented
Class	`attention`	Undocumented
Class	`attribution`	Undocumented
Class	`author`	Undocumented
Class	`authors`	Undocumented
Class	`BackLinkable`	Undocumented
Class	`Bibliographic`	Undocumented
Class	`block_quote`	Undocumented
Class	`Body`	Undocumented
Class	`bullet_list`	Undocumented
Class	`caption`	Undocumented
Class	`caution`	Undocumented
Class	`citation`	Undocumented
Class	`citation_reference`	Undocumented
Class	`classifier`	Undocumented
Class	`colspec`	Undocumented
Class	`comment`	Undocumented
Class	`compound`	Undocumented
Class	`contact`	Undocumented
Class	`container`	Undocumented
Class	`copyright`	Undocumented
Class	`danger`	Undocumented
Class	`date`	Undocumented
Class	`decoration`	Undocumented
Class	`Decorative`	Undocumented
Class	`definition`	Undocumented
Class	`definition_list`	Undocumented
Class	`definition_list_item`	Undocumented
Class	`description`	Undocumented
Class	`docinfo`	Undocumented
Class	`doctest_block`	Undocumented
Class	`document`	The document root element.
Class	`Element`	`Element` is the superclass to all specific elements.
Class	`emphasis`	Undocumented
Class	`entry`	Undocumented
Class	`enumerated_list`	Undocumented
Class	`error`	Undocumented
Class	`field`	Undocumented
Class	`field_body`	Undocumented
Class	`field_list`	Undocumented
Class	`field_name`	Undocumented
Class	`figure`	Undocumented
Class	`FixedTextElement`	An element which directly contains preformatted text.
Class	`footer`	Undocumented
Class	`footnote`	Undocumented
Class	`footnote_reference`	Undocumented
Class	`General`	Undocumented
Class	`generated`	Undocumented
Class	`GenericNodeVisitor`	Generic "Visitor" abstract superclass, for simple traversals.
Class	`header`	Undocumented
Class	`hint`	Undocumented
Class	`image`	Undocumented
Class	`important`	Undocumented
Class	`Inline`	Undocumented
Class	`inline`	Undocumented
Class	`Invisible`	Internal elements that don't appear in output.
Class	`label`	Undocumented
Class	`Labeled`	Contains a `label` as its first element.
Class	`legend`	Undocumented
Class	`line`	Undocumented
Class	`line_block`	Undocumented
Class	`list_item`	Undocumented
Class	`literal`	Undocumented
Class	`literal_block`	Undocumented
Class	`math`	Undocumented
Class	`math_block`	Undocumented
Class	`Node`	Abstract base class of nodes in a document tree.
Class	`NodeFound`	Raise to indicate that the target of a search has been found. This exception must be caught by the client; it is not caught by the traversal code.
Class	`NodeVisitor`	"Visitor" pattern [GoF95]_ abstract superclass implementation for document tree traversals.
Class	`note`	Undocumented
Class	`option`	Undocumented
Class	`option_argument`	Undocumented
Class	`option_group`	Undocumented
Class	`option_list`	Undocumented
Class	`option_list_item`	Undocumented
Class	`option_string`	Undocumented
Class	`organization`	Undocumented
Class	`paragraph`	Undocumented
Class	`Part`	Undocumented
Class	`pending`	No summary
Class	`PreBibliographic`	Category of Node which may occur before Bibliographic Nodes.
Class	`problematic`	Undocumented
Class	`raw`	Raw data that is to be passed untouched to the Writer.
Class	`reference`	Undocumented
Class	`Referential`	Undocumented
Class	`reprunicode`	A unicode sub-class that removes the initial u from unicode's repr.
Class	`Resolvable`	Undocumented
Class	`revision`	Undocumented
Class	`Root`	Undocumented
Class	`row`	Undocumented
Class	`rubric`	Undocumented
Class	`section`	Undocumented
Class	`Sequential`	List-like elements.
Class	`sidebar`	No summary
Class	`SkipChildren`	Do not visit any children of the current node. The current node's siblings and `depart_...` method are not affected.
Class	`SkipDeparture`	Do not call the current node's `depart_...` method. The current node's children and siblings are not affected.
Class	`SkipNode`	Do not visit the current node's children, and do not call the current node's `depart_...` method.
Class	`SkipSiblings`	Do not visit any more siblings (to the right) of the current node. The current node's children and its `depart_...` method are not affected.
Class	`SparseNodeVisitor`	No summary
Class	`Special`	Special internal body elements.
Class	`status`	Undocumented
Class	`StopTraversal`	No summary
Class	`strong`	Undocumented
Class	`Structural`	Undocumented
Class	`subscript`	Undocumented
Class	`substitution_definition`	Undocumented
Class	`substitution_reference`	Undocumented
Class	`subtitle`	Undocumented
Class	`superscript`	Undocumented
Class	`system_message`	System message element.
Class	`table`	Undocumented
Class	`target`	Undocumented
Class	`Targetable`	No class docstring; 1/2 class variable documented
Class	`tbody`	Undocumented
Class	`term`	Undocumented
Class	`Text`	Instances are terminal nodes (leaves) containing text only; no child nodes or attributes. Initialize by passing a string to the constructor. Access the text itself with the `astext` method.
Class	`TextElement`	An element which directly contains text.
Class	`tgroup`	Undocumented
Class	`thead`	Undocumented
Class	`tip`	Undocumented
Class	`title`	Undocumented
Class	`title_reference`	Undocumented
Class	`Titular`	Undocumented
Class	`topic`	Topics are terminal, "leaf" mini-sections, like block quotes with titles, or textual figures. A topic is just like a section, except that it has no subsections, and it doesn't have to conform to section placement rules.
Class	`transition`	Undocumented
Class	`TreeCopyVisitor`	Make a complete copy of a tree or branch, including element attributes.
Class	`TreePruningException`	Base class for `NodeVisitor`-related tree pruning exceptions.
Class	`version`	Undocumented
Class	`warning`	Undocumented
Function	`dupname`	Undocumented
Function	`ensure_str`	Failsave conversion of `unicode` to `str`.
Function	`fully_normalize_name`	Return a case- and whitespace-normalized name.
Function	`make_id`	Convert `string` into an identifier and return it.
Function	`pseudo_quoteattr`	Quote attributes for pseudo-xml
Function	`serial_escape`	Escape string values that are elements of a list, for serialization.
Function	`unescape`	Return a string with nulls removed or restored to backslashes. Backslash-escaped spaces are also removed.
Function	`whitespace_normalize_name`	Return a whitespace-normalized name.
Variable	`node_class_names`	A list of names of all concrete Node subclasses.
Class	`_traversal_list`	Undocumented
Function	`_add_node_class_names`	Save typing with dynamic assignments:
Function	`_call_default_departure`	Undocumented
Function	`_call_default_visit`	Undocumented
Function	`_nop`	Undocumented
Variable	`_non_id_at_ends`	Undocumented
Variable	`_non_id_chars`	Undocumented
Variable	`_non_id_translate`	Undocumented
Variable	`_non_id_translate_digraphs`	Undocumented

def dupname(node, name): (source)

Undocumented

def ensure_str(s): (source)

Failsave conversion of unicode to str.

def fully_normalize_name(name): (source)

Return a case- and whitespace-normalized name.

def make_id(string): (source)

Convert string into an identifier and return it.

Docutils identifiers will conform to the regular expression [a-z](-?[a-z0-9]+)*. For CSS compatibility, identifiers (the "class" and "id" attributes) should have no underscores, colons, or periods. Hyphens may be used.

The HTML 4.01 spec defines identifiers based on SGML tokens:

ID and NAME tokens must begin with a letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods (".").
However the CSS1 spec defines identifiers based on the "name" token, a tighter interpretation ("flex" tokenizer notation; "latin1" and "escape" 8-bit characters have been replaced with entities):
```
unicode     \[0-9a-f]{1,4}
latin1      [&iexcl;-&yuml;]
escape      {unicode}|\[ -~&iexcl;-&yuml;]
nmchar      [-a-z0-9]|{latin1}|{escape}
name        {nmchar}+
```

The CSS1 "nmchar" rule does not include underscores ("_"), colons (":"), or periods ("."), therefore "class" and "id" attributes should not contain these characters. They should be replaced with hyphens ("-"). Combined with HTML's requirements (the first character must be a letter; no "unicode", "latin1", or "escape" characters), this results in the [a-z](-?[a-z0-9]+)* pattern.

def pseudo_quoteattr(value): (source)

Quote attributes for pseudo-xml

def serial_escape(value): (source)

Escape string values that are elements of a list, for serialization.

def unescape(text, restore_backslashes=False, respect_whitespace=False): (source)

Return a string with nulls removed or restored to backslashes. Backslash-escaped spaces are also removed.

def whitespace_normalize_name(name): (source)

Return a whitespace-normalized name.

node_class_names = (source)

A list of names of all concrete Node subclasses.

def _add_node_class_names(names): (source)

Save typing with dynamic assignments:

def _call_default_departure(self, node): (source)

Undocumented

def _call_default_visit(self, node): (source)

Undocumented

def _nop(self, node): (source)

Undocumented

_non_id_at_ends = (source)

Undocumented

_non_id_chars = (source)

Undocumented

_non_id_translate: dict[int, str] = (source)

Undocumented

_non_id_translate_digraphs: dict[int, str] = (source)

Undocumented