4.4.1.1.7. nodes

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 docutils.nodes.Admonition

Bases: docutils.nodes.Body

class docutils.nodes.BackLinkable

Bases: object

add_backref(refid)

class docutils.nodes.Bibliographic

Bases: object

class docutils.nodes.Body

Bases: object

class docutils.nodes.Decorative

Bases: docutils.nodes.PreBibliographic

class docutils.nodes.Element(rawsource='', *children, **attributes)

Bases: docutils.nodes.Node

Element is the superclass to all specific elements.

Elements contain attributes and child nodes. Elements emulate dictionaries for attributes, indexing by attribute name (a string). To set the attribute ‘att’ to ‘value’, do:

element['att'] = 'value'

There are two special attributes: ‘ids’ and ‘names’. Both are lists of unique identifiers, and names serve as human interfaces to IDs. Names are case- and whitespace-normalized (see the fully_normalize_name() function), and IDs conform to the regular expression [a-z](-?[a-z0-9]+)* (see the make_id() function).

Elements also emulate lists for child nodes (element nodes and/or text nodes), indexing by integer. To get the first child node, use:

element[0]

Elements may be constructed using the += operator. To add one new child node to element, do:

element += node

This is equivalent to element.append(node).

To add a list of multiple child nodes at once, use the same += operator:

element += [node1, node2]

This is equivalent to element.extend([node1, node2]).

append(item)

append_attr_list(attr, values)

For each element in values, if it does not exist in self[attr], append it.

NOTE: Requires self[attr] and values to be sequence type and the former should specifically be a list.

astext()

attlist()

attributes = None

Dictionary of attribute {name: value}.

basic_attributes = ('ids', 'classes', 'names', 'dupnames')

List attributes which are defined for every Element-derived class instance and can be safely transferred to a different node.

child_text_separator = '\n\n'

Separator for child nodes, used by astext() method.

children = None

List of child nodes (elements and/or Text).

clear()

coerce_append_attr_list(attr, value)

First, convert both self[attr] and value to a non-string sequence type; if either is not already a sequence, convert it to a list of one element. Then call append_attr_list.

NOTE: self[attr] and value both must not be None.

copy()

copy_attr_coerce(attr, value, replace)

If attr is an attribute of self and either self[attr] or value is a list, convert all non-sequence values to a sequence of 1 element and then concatenate the two sequence, setting the result to self[attr]. If both self[attr] and value are non-sequences and replace is True or self[attr] is None, replace self[attr] with value. Otherwise, do nothing.

copy_attr_concatenate(attr, value, replace)

If attr is an attribute of self and both self[attr] and value are lists, concatenate the two sequences, setting the result to self[attr]. If either self[attr] or value are non-sequences and replace is True or self[attr] is None, replace self[attr] with value. Otherwise, do nothing.

copy_attr_consistent(attr, value, replace)

If replace is True or selfpattr] is None, replace self[attr] with value. Otherwise, do nothing.

copy_attr_convert(attr, value, replace=True)

If attr is an attribute of self, set self[attr] to [self[attr], value], otherwise set self[attr] to value.

NOTE: replace is not used by this function and is kept only for

compatibility with the other copy functions.

deepcopy()

delattr(attr)

emptytag()

endtag()

extend(item)

first_child_matching_class(childclass, start=0, end=9223372036854775807)

Return the index of the first child whose class exactly matches.

Parameters:

• childclass: A Node subclass to search for, or a tuple of Node classes. If a tuple, any of the classes may match.
• start: Initial index to check.
• end: Initial index to not check.

first_child_not_matching_class(childclass, start=0, end=9223372036854775807)

Return the index of the first child whose class does not match.

Parameters:

• childclass: A Node subclass to skip, or a tuple of Node classes. If a tuple, none of the classes may match.
• start: Initial index to check.
• end: Initial index to not check.

get(key, failobj=None)

get_language_code(fallback='')

Return node’s language tag.

Look iteratively in self and parents for a class argument starting with language- and return the remainder of it (which should be a BCP49 language tag) or the fallback.

has_key(attr)

hasattr(attr)

index(item)

insert(index, item)

is_not_default(key)

classmethod is_not_known_attribute(attr)

Returns True if and only if the given attribute is NOT recognized by this class.

classmethod is_not_list_attribute(attr)

Returns True if and only if the given attribute is NOT one of the basic list attributes defined for all Elements.

known_attributes = ('ids', 'classes', 'names', 'dupnames', 'backrefs', 'source')

List attributes that are known to the Element base class.

list_attributes = ('ids', 'classes', 'names', 'dupnames', 'backrefs')

List attributes, automatically initialized to empty lists for all nodes.

local_attributes = ('backrefs',)

A list of class-specific attributes that should not be copied with the standard attributes when replacing a node.

NOTE: Derived classes should override this value to prevent any of its attributes being copied by adding to the value in its parent class.

non_default_attributes()

note_referenced_by(name=None, id=None)

Note that this Element has been referenced by its name name or id id.

pformat(indent=' ', level=0)

pop(i=-1)

rawsource = None

The raw text from which this element was constructed.

remove(item)

replace(old, new)

Replace one child Node with another child or children.

replace_attr(attr, value, force=True)

If self[attr] does not exist or force is True or omitted, set self[attr] to value, otherwise do nothing.

replace_self(new)

Replace self node with new, where new is a node or a list of nodes.

set_class(name)

Add a new class to the “classes” attribute.

setdefault(key, failobj=None)

shortrepr()

starttag(quoteattr=None)

tagname = None

The element generic identifier. If None, it is set as an instance attribute to the name of the class.

update_all_atts(dict_, update_fun=<function Element.copy_attr_consistent>, replace=True, and_source=False)

Updates all attributes from node or dictionary dict_.

Appends the basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_, the two values are merged based on the value of update_fun. Generally, when replace is True, the values in self are replaced or merged with the values in dict_; otherwise, the values in self may be preserved or merged. When and_source is True, the ‘source’ attribute is included in the copy.

NOTE: When replace is False, and self contains a ‘source’ attribute,

‘source’ is not replaced even when dict_ has a ‘source’ attribute, though it may still be merged into a list depending on the value of update_fun.

NOTE: It is easier to call the update-specific methods then to pass

the update_fun method to this function.

update_all_atts_coercion(dict_, replace=True, and_source=False)

Updates all attributes from node or dictionary dict_.

Appends the basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_ whose values are both not lists and replace is True, the values in self are replaced with the values in dict_; if either of the values from self and dict_ for the given identifier are of list type, then first any non-lists are converted to 1-element lists and then the two lists are concatenated and the result stored in self; otherwise, the values in self are preserved. When and_source is True, the ‘source’ attribute is included in the copy.

NOTE: When replace is False, and self contains a ‘source’ attribute,

‘source’ is not replaced even when dict_ has a ‘source’ attribute, though it may still be merged into a list depending on the value of update_fun.

update_all_atts_concatenating(dict_, replace=True, and_source=False)

Updates all attributes from node or dictionary dict_.

Appends the basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_ whose values aren’t each lists and replace is True, the values in self are replaced with the values in dict_; if the values from self and dict_ for the given identifier are both of list type, then the two lists are concatenated and the result stored in self; otherwise, the values in self are preserved. When and_source is True, the ‘source’ attribute is included in the copy.

NOTE: When replace is False, and self contains a ‘source’ attribute,

‘source’ is not replaced even when dict_ has a ‘source’ attribute, though it may still be merged into a list depending on the value of update_fun.

update_all_atts_consistantly(dict_, replace=True, and_source=False)

Updates all attributes from node or dictionary dict_.

Appends the basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_ and replace is True, the values in self are replaced with the values in dict_; otherwise, the values in self are preserved. When and_source is True, the ‘source’ attribute is included in the copy.

NOTE: When replace is False, and self contains a ‘source’ attribute,

‘source’ is not replaced even when dict_ has a ‘source’ attribute, though it may still be merged into a list depending on the value of update_fun.

update_all_atts_convert(dict_, and_source=False)

Updates all attributes from node or dictionary dict_.

Appends the basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_ then first any non-lists are converted to 1-element lists and then the two lists are concatenated and the result stored in self; otherwise, the values in self are preserved. When and_source is True, the ‘source’ attribute is included in the copy.

NOTE: When replace is False, and self contains a ‘source’ attribute,

‘source’ is not replaced even when dict_ has a ‘source’ attribute, though it may still be merged into a list depending on the value of update_fun.

update_basic_atts(dict_)

Update basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) from node or dictionary dict_.

class docutils.nodes.FixedTextElement(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.TextElement

An element which directly contains preformatted text.

class docutils.nodes.General

Bases: docutils.nodes.Body

class docutils.nodes.GenericNodeVisitor(document)

Bases: docutils.nodes.NodeVisitor

Generic “Visitor” abstract superclass, for simple traversals.

Unless overridden, each visit_... method calls default_visit(), and each depart_... method (when using Node.walkabout()) calls default_departure(). default_visit() (and default_departure()) must be overridden in subclasses.

Define fully generic visitors by overriding default_visit() (and default_departure()) only. Define semi-generic visitors by overriding individual visit_...() (and depart_...()) methods also.

NodeVisitor.unknown_visit() (NodeVisitor.unknown_departure()) should be overridden for default behavior.

default_departure(node)

Override for generic, uniform traversals.

default_visit(node)

Override for generic, uniform traversals.

depart_GetTheCode(node)

depart_Text(node)

depart_abbreviation(node)

depart_acks(node)

depart_acronym(node)

depart_address(node)

depart_admonition(node)

depart_attention(node)

depart_attribution(node)

depart_author(node)

depart_authors(node)

depart_block_quote(node)

depart_bullet_list(node)

depart_caption(node)

depart_caution(node)

depart_centered(node)

depart_citation(node)

depart_citation_reference(node)

depart_classifier(node)

depart_colspec(node)

depart_comment(node)

depart_compact_paragraph(node)

depart_compound(node)

depart_contact(node)

depart_container(node)

depart_copyright(node)

depart_danger(node)

depart_date(node)

depart_decoration(node)

depart_definition(node)

depart_definition_list(node)

depart_definition_list_item(node)

depart_desc(node)

depart_desc_addname(node)

depart_desc_annotation(node)

depart_desc_classname(node)

depart_desc_content(node)

depart_desc_name(node)

depart_desc_optional(node)

depart_desc_parameter(node)

depart_desc_parameterlist(node)

depart_desc_returns(node)

depart_desc_signature(node)

depart_desc_signature_line(node)

depart_desc_type(node)

depart_description(node)

depart_displaymath(node)

depart_docinfo(node)

depart_doctest_block(node)

depart_document(node)

depart_download_reference(node)

depart_emphasis(node)

depart_entry(node)

depart_enumerated_list(node)

depart_eqref(node)

depart_error(node)

depart_field(node)

depart_field_body(node)

depart_field_list(node)

depart_field_name(node)

depart_figure(node)

depart_footer(node)

depart_footnote(node)

depart_footnote_reference(node)

depart_generated(node)

depart_glossary(node)

depart_header(node)

depart_highlightlang(node)

depart_hint(node)

depart_hlist(node)

depart_hlistcol(node)

depart_ifconfig(node)

depart_image(node)

depart_important(node)

depart_index(node)

depart_inline(node)

depart_label(node)

depart_legend(node)

depart_line(node)

depart_line_block(node)

depart_list_item(node)

depart_literal(node)

depart_literal_block(node)

depart_literal_emphasis(node)

depart_literal_strong(node)

depart_manpage(node)

depart_math(node)

depart_math_block(node)

depart_meta(node)

depart_not_smartquotable(node)

depart_note(node)

depart_number_reference(node)

depart_only(node)

depart_option(node)

depart_option_argument(node)

depart_option_group(node)

depart_option_list(node)

depart_option_list_item(node)

depart_option_string(node)

depart_organization(node)

depart_paragraph(node)

depart_pending(node)

depart_pending_xref(node)

depart_problematic(node)

depart_production(node)

depart_productionlist(node)

depart_raw(node)

depart_reference(node)

depart_revision(node)

depart_row(node)

depart_rubric(node)

depart_section(node)

depart_seealso(node)

depart_sidebar(node)

depart_start_of_file(node)

depart_status(node)

depart_strong(node)

depart_subscript(node)

depart_substitution_definition(node)

depart_substitution_reference(node)

depart_subtitle(node)

depart_superscript(node)

depart_system_message(node)

depart_table(node)

depart_tabular_col_spec(node)

depart_target(node)

depart_tbody(node)

depart_term(node)

depart_tgroup(node)

depart_thead(node)

depart_tip(node)

depart_title(node)

depart_title_reference(node)

depart_toctree(node)

depart_todo_node(node)

depart_todolist(node)

depart_topic(node)

depart_transition(node)

depart_translatable(node)

depart_version(node)

depart_versionmodified(node)

depart_warning(node)

visit_GetTheCode(node)

visit_Text(node)

visit_abbreviation(node)

visit_acks(node)

visit_acronym(node)

visit_address(node)

visit_admonition(node)

visit_attention(node)

visit_attribution(node)

visit_author(node)

visit_authors(node)

visit_block_quote(node)

visit_bullet_list(node)

visit_caption(node)

visit_caution(node)

visit_centered(node)

visit_citation(node)

visit_citation_reference(node)

visit_classifier(node)

visit_colspec(node)

visit_comment(node)

visit_compact_paragraph(node)

visit_compound(node)

visit_contact(node)

visit_container(node)

visit_copyright(node)

visit_danger(node)

visit_date(node)

visit_decoration(node)

visit_definition(node)

visit_definition_list(node)

visit_definition_list_item(node)

visit_desc(node)

visit_desc_addname(node)

visit_desc_annotation(node)

visit_desc_classname(node)

visit_desc_content(node)

visit_desc_name(node)

visit_desc_optional(node)

visit_desc_parameter(node)

visit_desc_parameterlist(node)

visit_desc_returns(node)

visit_desc_signature(node)

visit_desc_signature_line(node)

visit_desc_type(node)

visit_description(node)

visit_displaymath(node)

visit_docinfo(node)

visit_doctest_block(node)

visit_document(node)

visit_download_reference(node)

visit_emphasis(node)

visit_entry(node)

visit_enumerated_list(node)

visit_eqref(node)

visit_error(node)

visit_field(node)

visit_field_body(node)

visit_field_list(node)

visit_field_name(node)

visit_figure(node)

visit_footer(node)

visit_footnote(node)

visit_footnote_reference(node)

visit_generated(node)

visit_glossary(node)

visit_header(node)

visit_highlightlang(node)

visit_hint(node)

visit_hlist(node)

visit_hlistcol(node)

visit_ifconfig(node)

visit_image(node)

visit_important(node)

visit_index(node)

visit_inline(node)

visit_label(node)

visit_legend(node)

visit_line(node)

visit_line_block(node)

visit_list_item(node)

visit_literal(node)

visit_literal_block(node)

visit_literal_emphasis(node)

visit_literal_strong(node)

visit_manpage(node)

visit_math(node)

visit_math_block(node)

visit_meta(node)

visit_not_smartquotable(node)

visit_note(node)

visit_number_reference(node)

visit_only(node)

visit_option(node)

visit_option_argument(node)

visit_option_group(node)

visit_option_list(node)

visit_option_list_item(node)

visit_option_string(node)

visit_organization(node)

visit_paragraph(node)

visit_pending(node)

visit_pending_xref(node)

visit_problematic(node)

visit_production(node)

visit_productionlist(node)

visit_raw(node)

visit_reference(node)

visit_revision(node)

visit_row(node)

visit_rubric(node)

visit_section(node)

visit_seealso(node)

visit_sidebar(node)

visit_start_of_file(node)

visit_status(node)

visit_strong(node)

visit_subscript(node)

visit_substitution_definition(node)

visit_substitution_reference(node)

visit_subtitle(node)

visit_superscript(node)

visit_system_message(node)

visit_table(node)

visit_tabular_col_spec(node)

visit_target(node)

visit_tbody(node)

visit_term(node)

visit_tgroup(node)

visit_thead(node)

visit_tip(node)

visit_title(node)

visit_title_reference(node)

visit_toctree(node)

visit_todo_node(node)

visit_todolist(node)

visit_topic(node)

visit_transition(node)

visit_translatable(node)

visit_version(node)

visit_versionmodified(node)

visit_warning(node)

class docutils.nodes.Inline

Bases: object

class docutils.nodes.Invisible

Bases: docutils.nodes.PreBibliographic

Internal elements that don’t appear in output.

class docutils.nodes.Labeled

Bases: object

Contains a label as its first element.

class docutils.nodes.Node

Bases: object

Abstract base class of nodes in a document tree.

asdom(dom=None)

Return a DOM fragment representation of this Node.

copy()

Return a copy of self.

deepcopy()

Return a deep copy of self (also copying children).

document = None

The document node at the root of the tree containing this Node.

line = None

The line number (1-based) of the beginning of this Node in source.

next_node(condition=None, include_self=False, descend=True, siblings=False, ascend=False)

Return the first node in the iterable returned by traverse(), or None if the iterable is empty.

Parameter list is the same as of traverse. Note that include_self defaults to 0, though.

parent = None

Back-reference to the Node immediately containing this Node.

pformat(indent=' ', level=0)

Return an indented pseudo-XML representation, for test purposes.

Override in subclasses.

setup_child(child)

source = None

Path or description of the input source which generated this Node.

traverse(condition=None, include_self=True, descend=True, siblings=False, ascend=False)

Return an iterable containing

• self (if include_self is true)
• all descendants in tree traversal order (if descend is true)
• all siblings (if siblings is true) and their descendants (if also descend is true)
• the siblings of the parent (if ascend is true) and their descendants (if also descend is true), and so on

If condition is not None, the iterable contains only nodes for which condition(node) is true. If condition is a node class cls, it is equivalent to a function consisting of return isinstance(node, cls).

If ascend is true, assume siblings to be true as well.

For example, given the following tree:

<paragraph>
    <emphasis>      <--- emphasis.traverse() and
        <strong>    <--- strong.traverse() are called.
            Foo
        Bar
    <reference name="Baz" refid="baz">
        Baz

Then list(emphasis.traverse()) equals

[<emphasis>, <strong>, <#text: Foo>, <#text: Bar>]

and list(strong.traverse(ascend=True)) equals

[<strong>, <#text: Foo>, <#text: Bar>, <reference>, <#text: Baz>]

walk(visitor)

Traverse a tree of Node objects, calling the dispatch_visit() method of visitor when entering each node. (The walkabout() method is similar, except it also calls the dispatch_departure() method before exiting each node.)

This tree traversal supports limited in-place tree modifications. Replacing one node with one or more nodes is OK, as is removing an element. However, if the node removed or replaced occurs after the current node, the old node will still be traversed, and any new nodes will not.

Within visit methods (and depart methods for walkabout()), TreePruningException subclasses may be raised (SkipChildren, SkipSiblings, SkipNode, SkipDeparture).

Parameter visitor: A NodeVisitor object, containing a visit implementation for each Node subclass encountered.

Return true if we should stop the traversal.

walkabout(visitor)

Perform a tree traversal similarly to Node.walk() (which see), except also call the dispatch_departure() method before exiting each node.

Parameter visitor: A NodeVisitor object, containing a visit and depart implementation for each Node subclass encountered.

Return true if we should stop the traversal.

exception docutils.nodes.NodeFound

Bases: docutils.nodes.TreePruningException

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 docutils.nodes.NodeVisitor(document)

Bases: object

“Visitor” pattern [GoF95] abstract superclass implementation for document tree traversals.

Each node class has corresponding methods, doing nothing by default; override individual methods for specific and useful behaviour. The dispatch_visit() method is called by Node.walk() upon entering a node. Node.walkabout() also calls the dispatch_departure() method before exiting a node.

The dispatch methods call “visit_ + node class name” or “depart_ + node class name”, resp.

This is a base class for visitors whose visit_... & depart_... methods should be implemented for all node types encountered (such as for docutils.writers.Writer subclasses). Unimplemented methods will raise exceptions.

For sparse traversals, where only certain node types are of interest, subclass SparseNodeVisitor instead. When (mostly or entirely) uniform processing is desired, subclass GenericNodeVisitor.

[GoF95]

Gamma, Helm, Johnson, Vlissides. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley, Reading, MA, USA, 1995.

dispatch_departure(node)

Call self.”depart_ + node class name” with node as parameter. If the depart_... method does not exist, call self.unknown_departure.

dispatch_visit(node)

Call self.”visit_ + node class name” with node as parameter. If the visit_... method does not exist, call self.unknown_visit.

optional = ()

Tuple containing node class names (as strings).

No exception will be raised if writers do not implement visit or departure functions for these node classes.

Used to ensure transitional compatibility with existing 3rd-party writers.

unknown_departure(node)

Called before exiting unknown Node types.

Raise exception unless overridden.

unknown_visit(node)

Called when entering unknown Node types.

Raise an exception unless overridden.

class docutils.nodes.Part

Bases: object

class docutils.nodes.PreBibliographic

Bases: object

Category of Node which may occur before Bibliographic Nodes.

class docutils.nodes.Referential

Bases: docutils.nodes.Resolvable

class docutils.nodes.Resolvable

Bases: object

resolved = 0

class docutils.nodes.Root

Bases: object

class docutils.nodes.Sequential

Bases: docutils.nodes.Body

List-like elements.

exception docutils.nodes.SkipChildren

Bases: docutils.nodes.TreePruningException

Do not visit any children of the current node. The current node’s siblings and depart_... method are not affected.

exception docutils.nodes.SkipDeparture

Bases: docutils.nodes.TreePruningException

Do not call the current node’s depart_... method. The current node’s children and siblings are not affected.

exception docutils.nodes.SkipNode

Bases: docutils.nodes.TreePruningException

Do not visit the current node’s children, and do not call the current node’s depart_... method.

exception docutils.nodes.SkipSiblings

Bases: docutils.nodes.TreePruningException

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 docutils.nodes.SparseNodeVisitor(document)

Bases: docutils.nodes.NodeVisitor

Base class for sparse traversals, where only certain node types are of interest. When visit_... & depart_... methods should be implemented for all node types (such as for docutils.writers.Writer subclasses), subclass NodeVisitor instead.

depart_GetTheCode(node)

depart_Text(node)

depart_abbreviation(node)

depart_acks(node)

depart_acronym(node)

depart_address(node)

depart_admonition(node)

depart_attention(node)

depart_attribution(node)

depart_author(node)

depart_authors(node)

depart_block_quote(node)

depart_bullet_list(node)

depart_caption(node)

depart_caution(node)

depart_centered(node)

depart_citation(node)

depart_citation_reference(node)

depart_classifier(node)

depart_colspec(node)

depart_comment(node)

depart_compact_paragraph(node)

depart_compound(node)

depart_contact(node)

depart_container(node)

depart_copyright(node)

depart_danger(node)

depart_date(node)

depart_decoration(node)

depart_definition(node)

depart_definition_list(node)

depart_definition_list_item(node)

depart_desc(node)

depart_desc_addname(node)

depart_desc_annotation(node)

depart_desc_classname(node)

depart_desc_content(node)

depart_desc_name(node)

depart_desc_optional(node)

depart_desc_parameter(node)

depart_desc_parameterlist(node)

depart_desc_returns(node)

depart_desc_signature(node)

depart_desc_signature_line(node)

depart_desc_type(node)

depart_description(node)

depart_displaymath(node)

depart_docinfo(node)

depart_doctest_block(node)

depart_document(node)

depart_download_reference(node)

depart_emphasis(node)

depart_entry(node)

depart_enumerated_list(node)

depart_eqref(node)

depart_error(node)

depart_field(node)

depart_field_body(node)

depart_field_list(node)

depart_field_name(node)

depart_figure(node)

depart_footer(node)

depart_footnote(node)

depart_footnote_reference(node)

depart_generated(node)

depart_glossary(node)

depart_header(node)

depart_highlightlang(node)

depart_hint(node)

depart_hlist(node)

depart_hlistcol(node)

depart_ifconfig(node)

depart_image(node)

depart_important(node)

depart_index(node)

depart_inline(node)

depart_label(node)

depart_legend(node)

depart_line(node)

depart_line_block(node)

depart_list_item(node)

depart_literal(node)

depart_literal_block(node)

depart_literal_emphasis(node)

depart_literal_strong(node)

depart_manpage(node)

depart_math(node)

depart_math_block(node)

depart_meta(node)

depart_not_smartquotable(node)

depart_note(node)

depart_number_reference(node)

depart_only(node)

depart_option(node)

depart_option_argument(node)

depart_option_group(node)

depart_option_list(node)

depart_option_list_item(node)

depart_option_string(node)

depart_organization(node)

depart_paragraph(node)

depart_pending(node)

depart_pending_xref(node)

depart_problematic(node)

depart_production(node)

depart_productionlist(node)

depart_raw(node)

depart_reference(node)

depart_revision(node)

depart_row(node)

depart_rubric(node)

depart_section(node)

depart_seealso(node)

depart_sidebar(node)

depart_start_of_file(node)

depart_status(node)

depart_strong(node)

depart_subscript(node)

depart_substitution_definition(node)

depart_substitution_reference(node)

depart_subtitle(node)

depart_superscript(node)

depart_system_message(node)

depart_table(node)

depart_tabular_col_spec(node)

depart_target(node)

depart_tbody(node)

depart_term(node)

depart_tgroup(node)

depart_thead(node)

depart_tip(node)

depart_title(node)

depart_title_reference(node)

depart_toctree(node)

depart_todo_node(node)

depart_todolist(node)

depart_topic(node)

depart_transition(node)

depart_translatable(node)

depart_version(node)

depart_versionmodified(node)

depart_warning(node)

visit_GetTheCode(node)

visit_Text(node)

visit_abbreviation(node)

visit_acks(node)

visit_acronym(node)

visit_address(node)

visit_admonition(node)

visit_attention(node)

visit_attribution(node)

visit_author(node)

visit_authors(node)

visit_block_quote(node)

visit_bullet_list(node)

visit_caption(node)

visit_caution(node)

visit_centered(node)

visit_citation(node)

visit_citation_reference(node)

visit_classifier(node)

visit_colspec(node)

visit_comment(node)

visit_compact_paragraph(node)

visit_compound(node)

visit_contact(node)

visit_container(node)

visit_copyright(node)

visit_danger(node)

visit_date(node)

visit_decoration(node)

visit_definition(node)

visit_definition_list(node)

visit_definition_list_item(node)

visit_desc(node)

visit_desc_addname(node)

visit_desc_annotation(node)

visit_desc_classname(node)

visit_desc_content(node)

visit_desc_name(node)

visit_desc_optional(node)

visit_desc_parameter(node)

visit_desc_parameterlist(node)

visit_desc_returns(node)

visit_desc_signature(node)

visit_desc_signature_line(node)

visit_desc_type(node)

visit_description(node)

visit_displaymath(node)

visit_docinfo(node)

visit_doctest_block(node)

visit_document(node)

visit_download_reference(node)

visit_emphasis(node)

visit_entry(node)

visit_enumerated_list(node)

visit_eqref(node)

visit_error(node)

visit_field(node)

visit_field_body(node)

visit_field_list(node)

visit_field_name(node)

visit_figure(node)

visit_footer(node)

visit_footnote(node)

visit_footnote_reference(node)

visit_generated(node)

visit_glossary(node)

visit_header(node)

visit_highlightlang(node)

visit_hint(node)

visit_hlist(node)

visit_hlistcol(node)

visit_ifconfig(node)

visit_image(node)

visit_important(node)

visit_index(node)

visit_inline(node)

visit_label(node)

visit_legend(node)

visit_line(node)

visit_line_block(node)

visit_list_item(node)

visit_literal(node)

visit_literal_block(node)

visit_literal_emphasis(node)

visit_literal_strong(node)

visit_manpage(node)

visit_math(node)

visit_math_block(node)

visit_meta(node)

visit_not_smartquotable(node)

visit_note(node)

visit_number_reference(node)

visit_only(node)

visit_option(node)

visit_option_argument(node)

visit_option_group(node)

visit_option_list(node)

visit_option_list_item(node)

visit_option_string(node)

visit_organization(node)

visit_paragraph(node)

visit_pending(node)

visit_pending_xref(node)

visit_problematic(node)

visit_production(node)

visit_productionlist(node)

visit_raw(node)

visit_reference(node)

visit_revision(node)

visit_row(node)

visit_rubric(node)

visit_section(node)

visit_seealso(node)

visit_sidebar(node)

visit_start_of_file(node)

visit_status(node)

visit_strong(node)

visit_subscript(node)

visit_substitution_definition(node)

visit_substitution_reference(node)

visit_subtitle(node)

visit_superscript(node)

visit_system_message(node)

visit_table(node)

visit_tabular_col_spec(node)

visit_target(node)

visit_tbody(node)

visit_term(node)

visit_tgroup(node)

visit_thead(node)

visit_tip(node)

visit_title(node)

visit_title_reference(node)

visit_toctree(node)

visit_todo_node(node)

visit_todolist(node)

visit_topic(node)

visit_transition(node)

visit_translatable(node)

visit_version(node)

visit_versionmodified(node)

visit_warning(node)

class docutils.nodes.Special

Bases: docutils.nodes.Body

Special internal body elements.

exception docutils.nodes.StopTraversal

Bases: docutils.nodes.TreePruningException

Stop the traversal alltogether. The current node’s depart_... method is not affected. The parent nodes depart_... methods are also called as usual. No other nodes are visited. This is an alternative to NodeFound that does not cause exception handling to trickle up to the caller.

class docutils.nodes.Structural

Bases: object

class docutils.nodes.Targetable

Bases: docutils.nodes.Resolvable

indirect_reference_name = None

Holds the whitespace_normalized_name (contains mixed case) of a target. Required for MoinMoin/reST compatibility.

referenced = 0

class docutils.nodes.Text(data, rawsource='')

Bases: docutils.nodes.Node, str

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.

Prevent the rawsource argument from propagating to str.

astext()

children = ()

Text nodes have no children, and cannot have children.

copy()

deepcopy()

lstrip(chars=None)

pformat(indent=' ', level=0)

rawsource = None

The raw text from which this element was constructed.

rstrip(chars=None)

shortrepr(maxlen=18)

tagname = '#text'

class docutils.nodes.TextElement(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Element

An element which directly contains text.

Its children are all Text or Inline subclass nodes. You can check whether an element’s context is inline simply by checking whether its immediate parent is a TextElement instance (including subclasses). This is handy for nodes like image that can appear both inline and as standalone body elements.

If passing children to __init__(), make sure to set text to '' or some other suitable value.

child_text_separator = ''

Separator for child nodes, used by astext() method.

class docutils.nodes.Titular

Bases: object

class docutils.nodes.TreeCopyVisitor(document)

Bases: docutils.nodes.GenericNodeVisitor

Make a complete copy of a tree or branch, including element attributes.

default_departure(node)

Restore the previous acting parent.

default_visit(node)

Copy the current node, and make it the new acting parent.

get_tree_copy()

exception docutils.nodes.TreePruningException

Bases: Exception

Base class for NodeVisitor-related tree pruning exceptions.

Raise subclasses from within visit_... or depart_... methods called from Node.walk() and Node.walkabout() tree traversals to prune the tree traversed.

class docutils.nodes.abbreviation(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Inline, docutils.nodes.TextElement

class docutils.nodes.acronym(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Inline, docutils.nodes.TextElement

class docutils.nodes.address(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Bibliographic, docutils.nodes.FixedTextElement

class docutils.nodes.admonition(rawsource='', *children, **attributes)

Bases: docutils.nodes.Admonition, docutils.nodes.Element

class docutils.nodes.attention(rawsource='', *children, **attributes)

Bases: docutils.nodes.Admonition, docutils.nodes.Element

class docutils.nodes.attribution(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.TextElement

class docutils.nodes.author(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Bibliographic, docutils.nodes.TextElement

class docutils.nodes.authors(rawsource='', *children, **attributes)

Bases: docutils.nodes.Bibliographic, docutils.nodes.Element

class docutils.nodes.block_quote(rawsource='', *children, **attributes)

Bases: docutils.nodes.General, docutils.nodes.Element

class docutils.nodes.bullet_list(rawsource='', *children, **attributes)

Bases: docutils.nodes.Sequential, docutils.nodes.Element

class docutils.nodes.caption(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.TextElement

class docutils.nodes.caution(rawsource='', *children, **attributes)

Bases: docutils.nodes.Admonition, docutils.nodes.Element

class docutils.nodes.citation(rawsource='', *children, **attributes)

Bases: docutils.nodes.General, docutils.nodes.BackLinkable, docutils.nodes.Element, docutils.nodes.Labeled, docutils.nodes.Targetable

class docutils.nodes.citation_reference(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Inline, docutils.nodes.Referential, docutils.nodes.TextElement

class docutils.nodes.classifier(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.TextElement

class docutils.nodes.colspec(rawsource='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.Element

class docutils.nodes.comment(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Special, docutils.nodes.Invisible, docutils.nodes.FixedTextElement

class docutils.nodes.compound(rawsource='', *children, **attributes)

Bases: docutils.nodes.General, docutils.nodes.Element

class docutils.nodes.contact(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Bibliographic, docutils.nodes.TextElement

class docutils.nodes.container(rawsource='', *children, **attributes)

Bases: docutils.nodes.General, docutils.nodes.Element

class docutils.nodes.copyright(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Bibliographic, docutils.nodes.TextElement

class docutils.nodes.danger(rawsource='', *children, **attributes)

Bases: docutils.nodes.Admonition, docutils.nodes.Element

class docutils.nodes.date(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Bibliographic, docutils.nodes.TextElement

class docutils.nodes.decoration(rawsource='', *children, **attributes)

Bases: docutils.nodes.Decorative, docutils.nodes.Element

get_footer()

get_header()

class docutils.nodes.definition(rawsource='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.Element

class docutils.nodes.definition_list(rawsource='', *children, **attributes)

Bases: docutils.nodes.Sequential, docutils.nodes.Element

class docutils.nodes.definition_list_item(rawsource='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.Element

class docutils.nodes.description(rawsource='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.Element

class docutils.nodes.docinfo(rawsource='', *children, **attributes)

Bases: docutils.nodes.Bibliographic, docutils.nodes.Element

class docutils.nodes.doctest_block(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.General, docutils.nodes.FixedTextElement

class docutils.nodes.document(settings, reporter, *args, **kwargs)

Bases: docutils.nodes.Root, docutils.nodes.Structural, docutils.nodes.Element

The document root element.

Do not instantiate this class directly; use docutils.utils.new_document() instead.

asdom(dom=None)

Return a DOM representation of this document.

autofootnote_refs = None

List of auto-numbered footnote_reference nodes.

autofootnote_start = None

Initial auto-numbered footnote number.

autofootnotes = None

List of auto-numbered footnote nodes.

citation_refs = None

Mapping of citation labels to lists of citation_reference nodes.

citations = None

List of citation nodes.

copy()

current_line = None

Line number (1-based) of current_source.

current_source = None

Path to or description of the input source being processed.

decoration = None

Document’s decoration node.

footnote_refs = None

Mapping of footnote labels to lists of footnote_reference nodes.

footnotes = None

List of manually-numbered footnote nodes.

get_decoration()

has_name(name)

id_start = None

Initial ID number.

ids = None

Mapping of ids to nodes.

indirect_targets = None

List of indirect target nodes.

nameids = None

Mapping of names to unique id’s.

nametypes = None

Mapping of names to hyperlink type (boolean: True => explicit, False => implicit.

note_anonymous_target(target)

note_autofootnote(footnote)

note_autofootnote_ref(ref)

note_citation(citation)

note_citation_ref(ref)

note_explicit_target(target, msgnode=None)

note_footnote(footnote)

note_footnote_ref(ref)

note_implicit_target(target, msgnode=None)

note_indirect_target(target)

note_parse_message(message)

note_pending(pending, priority=None)

note_refid(node)

note_refname(node)

note_source(source, offset)

note_substitution_def(subdef, def_name, msgnode=None)

note_substitution_ref(subref, refname)

note_symbol_footnote(footnote)

note_symbol_footnote_ref(ref)

note_transform_message(message)

parse_messages = None

System messages generated while parsing.

refids = None

Mapping of ids to lists of referencing nodes.

refnames = None

Mapping of names to lists of referencing nodes.

reporter = None

System message generator.

set_duplicate_name_id(node, id, name, msgnode, explicit)

set_id(node, msgnode=None)

set_name_id_map(node, id, msgnode=None, explicit=None)

self.nameids maps names to IDs, while self.nametypes maps names to booleans representing hyperlink type (True==explicit, False==implicit). This method updates the mappings.

The following state transition table shows how self.nameids (“ids”) and self.nametypes (“types”) change with new input (a call to this method), and what actions are performed (“implicit”-type system messages are INFO/1, and “explicit”-type system messages are ERROR/3):

Old State		Input	Action		New State		Notes
ids	types	new type	sys.msg.	dupname	ids	types
		explicit			new	True
		implicit			new	False
None	False	explicit			new	True
old	False	explicit	implicit	old	new	True
None	True	explicit	explicit	new	None	True
old	True	explicit	explicit	new,old	None	True	[1]
None	False	implicit	implicit	new	None	False
old	False	implicit	implicit	new,old	None	False
None	True	implicit	implicit	new	None	True
old	True	implicit	implicit	new	old	True

[1]	Do not clear the name-to-id map or invalidate the old target if both old and new targets are external and refer to identical URIs. The new target is invalidated regardless.

settings = None

Runtime settings data record.

substitution_defs = None

Mapping of substitution names to substitution_definition nodes.

substitution_names = None

Mapping of case-normalized substitution names to case-sensitive names.

symbol_footnote_refs = None

List of symbol footnote_reference nodes.

symbol_footnote_start = None

Initial symbol footnote symbol index.

symbol_footnotes = None

List of symbol footnote nodes.

transform_messages = None

System messages generated while applying transforms.

transformer = None

Storage for transforms to be applied to this document.

docutils.nodes.dupname(node, name)

class docutils.nodes.emphasis(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Inline, docutils.nodes.TextElement

docutils.nodes.ensure_str(s)

Failsave conversion of unicode to str.

class docutils.nodes.entry(rawsource='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.Element

class docutils.nodes.enumerated_list(rawsource='', *children, **attributes)

Bases: docutils.nodes.Sequential, docutils.nodes.Element

class docutils.nodes.error(rawsource='', *children, **attributes)

Bases: docutils.nodes.Admonition, docutils.nodes.Element

class docutils.nodes.field(rawsource='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.Element

class docutils.nodes.field_body(rawsource='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.Element

class docutils.nodes.field_list(rawsource='', *children, **attributes)

Bases: docutils.nodes.Sequential, docutils.nodes.Element

class docutils.nodes.field_name(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.TextElement

class docutils.nodes.figure(rawsource='', *children, **attributes)

Bases: docutils.nodes.General, docutils.nodes.Element

class docutils.nodes.footer(rawsource='', *children, **attributes)

Bases: docutils.nodes.Decorative, docutils.nodes.Element

class docutils.nodes.footnote(rawsource='', *children, **attributes)

Bases: docutils.nodes.General, docutils.nodes.BackLinkable, docutils.nodes.Element, docutils.nodes.Labeled, docutils.nodes.Targetable

class docutils.nodes.footnote_reference(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Inline, docutils.nodes.Referential, docutils.nodes.TextElement

docutils.nodes.fully_normalize_name(name)

Return a case- and whitespace-normalized name.

class docutils.nodes.generated(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Inline, docutils.nodes.TextElement

class docutils.nodes.header(rawsource='', *children, **attributes)

Bases: docutils.nodes.Decorative, docutils.nodes.Element

class docutils.nodes.hint(rawsource='', *children, **attributes)

Bases: docutils.nodes.Admonition, docutils.nodes.Element

class docutils.nodes.image(rawsource='', *children, **attributes)

Bases: docutils.nodes.General, docutils.nodes.Inline, docutils.nodes.Element

astext()

class docutils.nodes.important(rawsource='', *children, **attributes)

Bases: docutils.nodes.Admonition, docutils.nodes.Element

class docutils.nodes.inline(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Inline, docutils.nodes.TextElement

class docutils.nodes.label(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.TextElement

class docutils.nodes.legend(rawsource='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.Element

class docutils.nodes.line(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.TextElement

indent = None

class docutils.nodes.line_block(rawsource='', *children, **attributes)

Bases: docutils.nodes.General, docutils.nodes.Element

class docutils.nodes.list_item(rawsource='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.Element

class docutils.nodes.literal(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Inline, docutils.nodes.TextElement

class docutils.nodes.literal_block(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.General, docutils.nodes.FixedTextElement

docutils.nodes.make_id(string)

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      [¡-ÿ]
  escape      {unicode}|\[ -~¡-ÿ]
  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.

class docutils.nodes.math(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Inline, docutils.nodes.TextElement

class docutils.nodes.math_block(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.General, docutils.nodes.FixedTextElement

docutils.nodes.node_class_names = ['Text', 'abbreviation', 'acronym', 'address', 'admonition', 'attention', 'attribution', 'author', 'authors', 'block_quote', 'bullet_list', 'caption', 'caution', 'citation', 'citation_reference', 'classifier', 'colspec', 'comment', 'compound', 'contact', 'container', 'copyright', 'danger', 'date', 'decoration', 'definition', 'definition_list', 'definition_list_item', 'description', 'docinfo', 'doctest_block', 'document', 'emphasis', 'entry', 'enumerated_list', 'error', 'field', 'field_body', 'field_list', 'field_name', 'figure', 'footer', 'footnote', 'footnote_reference', 'generated', 'header', 'hint', 'image', 'important', 'inline', 'label', 'legend', 'line', 'line_block', 'list_item', 'literal', 'literal_block', 'math', 'math_block', 'note', 'option', 'option_argument', 'option_group', 'option_list', 'option_list_item', 'option_string', 'organization', 'paragraph', 'pending', 'problematic', 'raw', 'reference', 'revision', 'row', 'rubric', 'section', 'sidebar', 'status', 'strong', 'subscript', 'substitution_definition', 'substitution_reference', 'subtitle', 'superscript', 'system_message', 'table', 'target', 'tbody', 'term', 'tgroup', 'thead', 'tip', 'title', 'title_reference', 'topic', 'transition', 'version', 'warning']

A list of names of all concrete Node subclasses.

class docutils.nodes.note(rawsource='', *children, **attributes)

Bases: docutils.nodes.Admonition, docutils.nodes.Element

class docutils.nodes.option(rawsource='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.Element

child_text_separator = ''

class docutils.nodes.option_argument(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.TextElement

astext()

class docutils.nodes.option_group(rawsource='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.Element

child_text_separator = ', '

class docutils.nodes.option_list(rawsource='', *children, **attributes)

Bases: docutils.nodes.Sequential, docutils.nodes.Element

class docutils.nodes.option_list_item(rawsource='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.Element

child_text_separator = ' '

class docutils.nodes.option_string(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.TextElement

class docutils.nodes.organization(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Bibliographic, docutils.nodes.TextElement

class docutils.nodes.paragraph(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.General, docutils.nodes.TextElement

class docutils.nodes.pending(transform, details=None, rawsource='', *children, **attributes)

Bases: docutils.nodes.Special, docutils.nodes.Invisible, docutils.nodes.Element

The “pending” element is used to encapsulate a pending operation: the operation (transform), the point at which to apply it, and any data it requires. Only the pending operation’s location within the document is stored in the public document tree (by the “pending” object itself); the operation and its data are stored in the “pending” object’s internal instance attributes.

For example, say you want a table of contents in your reStructuredText document. The easiest way to specify where to put it is from within the document, with a directive:

.. contents::

But the “contents” directive can’t do its work until the entire document has been parsed and possibly transformed to some extent. So the directive code leaves a placeholder behind that will trigger the second phase of its processing, something like this:

<pending ...public attributes...> + internal attributes

Use document.note_pending() so that the docutils.transforms.Transformer stage of processing can run all pending transforms.

copy()

details = None

Detail data (dictionary) required by the pending operation.

pformat(indent=' ', level=0)

transform = None

The docutils.transforms.Transform class implementing the pending operation.

class docutils.nodes.problematic(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Inline, docutils.nodes.TextElement

docutils.nodes.pseudo_quoteattr(value)

Quote attributes for pseudo-xml

class docutils.nodes.raw(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Special, docutils.nodes.Inline, docutils.nodes.PreBibliographic, docutils.nodes.FixedTextElement

Raw data that is to be passed untouched to the Writer.

class docutils.nodes.reference(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.General, docutils.nodes.Inline, docutils.nodes.Referential, docutils.nodes.TextElement

class docutils.nodes.revision(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Bibliographic, docutils.nodes.TextElement

class docutils.nodes.row(rawsource='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.Element

class docutils.nodes.rubric(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Titular, docutils.nodes.TextElement

class docutils.nodes.section(rawsource='', *children, **attributes)

Bases: docutils.nodes.Structural, docutils.nodes.Element

docutils.nodes.serial_escape(value)

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

class docutils.nodes.sidebar(rawsource='', *children, **attributes)

Bases: docutils.nodes.Structural, docutils.nodes.Element

Sidebars are like miniature, parallel documents that occur inside other documents, providing related or reference material. A sidebar is typically offset by a border and “floats” to the side of the page; the document’s main text may flow around it. Sidebars can also be likened to super-footnotes; their content is outside of the flow of the document’s main text.

Sidebars are allowed wherever body elements (list, table, etc.) are allowed, but only at the top level of a section or document. Sidebars cannot nest inside sidebars, topics, or body elements; you can’t have a sidebar inside a table, list, block quote, etc.

class docutils.nodes.status(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Bibliographic, docutils.nodes.TextElement

class docutils.nodes.strong(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Inline, docutils.nodes.TextElement

class docutils.nodes.subscript(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Inline, docutils.nodes.TextElement

class docutils.nodes.substitution_definition(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Special, docutils.nodes.Invisible, docutils.nodes.TextElement

class docutils.nodes.substitution_reference(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Inline, docutils.nodes.TextElement

class docutils.nodes.subtitle(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Titular, docutils.nodes.PreBibliographic, docutils.nodes.TextElement

class docutils.nodes.superscript(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Inline, docutils.nodes.TextElement

class docutils.nodes.system_message(message=None, *children, **attributes)

Bases: docutils.nodes.Special, docutils.nodes.BackLinkable, docutils.nodes.PreBibliographic, docutils.nodes.Element

System message element.

Do not instantiate this class directly; use document.reporter.info/warning/error/severe() instead.

astext()

class docutils.nodes.table(rawsource='', *children, **attributes)

Bases: docutils.nodes.General, docutils.nodes.Element

class docutils.nodes.target(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Special, docutils.nodes.Invisible, docutils.nodes.Inline, docutils.nodes.TextElement, docutils.nodes.Targetable

class docutils.nodes.tbody(rawsource='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.Element

class docutils.nodes.term(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.TextElement

class docutils.nodes.tgroup(rawsource='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.Element

class docutils.nodes.thead(rawsource='', *children, **attributes)

Bases: docutils.nodes.Part, docutils.nodes.Element

class docutils.nodes.tip(rawsource='', *children, **attributes)

Bases: docutils.nodes.Admonition, docutils.nodes.Element

class docutils.nodes.title(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Titular, docutils.nodes.PreBibliographic, docutils.nodes.TextElement

class docutils.nodes.title_reference(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Inline, docutils.nodes.TextElement

class docutils.nodes.topic(rawsource='', *children, **attributes)

Bases: docutils.nodes.Structural, docutils.nodes.Element

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.

Topics are allowed wherever body elements (list, table, etc.) are allowed, but only at the top level of a section or document. Topics cannot nest inside topics, sidebars, or body elements; you can’t have a topic inside a table, list, block quote, etc.

class docutils.nodes.transition(rawsource='', *children, **attributes)

Bases: docutils.nodes.Structural, docutils.nodes.Element

class docutils.nodes.version(rawsource='', text='', *children, **attributes)

Bases: docutils.nodes.Bibliographic, docutils.nodes.TextElement

class docutils.nodes.warning(rawsource='', *children, **attributes)

Bases: docutils.nodes.Admonition, docutils.nodes.Element

docutils.nodes.whitespace_normalize_name(name)

Return a whitespace-normalized name.