docutils.transforms.references module

Transforms for resolving references.

class PropagateTargets(document, startnode=None)

Bases: Transform

Propagate empty internal targets to the next element.

Given the following nodes:

<target ids="internal1" names="internal1">
<target anonymous="1" ids="id1">
<target ids="internal2" names="internal2">
<paragraph>
    This is a test.

PropagateTargets propagates the ids and names of the internal targets preceding the paragraph to the paragraph itself:

<target refid="internal1">
<target anonymous="1" refid="id1">
<target refid="internal2">
<paragraph ids="internal2 id1 internal1" names="internal2 internal1">
    This is a test.

default_priority = 260

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

apply()

Override to apply the transform to the document tree.

class AnonymousHyperlinks(document, startnode=None)

Bases: Transform

Link anonymous references to targets. Given:

<paragraph>
    <reference anonymous="1">
        internal
    <reference anonymous="1">
        external
<target anonymous="1" ids="id1">
<target anonymous="1" ids="id2" refuri="http://external">

Corresponding references are linked via “refid” or resolved via “refuri”:

<paragraph>
    <reference anonymous="1" refid="id1">
        text
    <reference anonymous="1" refuri="http://external">
        external
<target anonymous="1" ids="id1">
<target anonymous="1" ids="id2" refuri="http://external">

default_priority = 440

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

apply()

Override to apply the transform to the document tree.

class IndirectHyperlinks(document, startnode=None)

Bases: Transform

1. Indirect external references:

   <paragraph>
       <reference refname="indirect external">
           indirect external
   <target id="id1" name="direct external"
       refuri="http://indirect">
   <target id="id2" name="indirect external"
       refname="direct external">
   

   The “refuri” attribute is migrated back to all indirect targets from the final direct target (i.e. a target not referring to another indirect target):

   <paragraph>
       <reference refname="indirect external">
           indirect external
   <target id="id1" name="direct external"
       refuri="http://indirect">
   <target id="id2" name="indirect external"
       refuri="http://indirect">
   

   Once the attribute is migrated, the preexisting “refname” attribute is dropped.

2. Indirect internal references:

   <target id="id1" name="final target">
   <paragraph>
       <reference refname="indirect internal">
           indirect internal
   <target id="id2" name="indirect internal 2"
       refname="final target">
   <target id="id3" name="indirect internal"
       refname="indirect internal 2">
   

   Targets which indirectly refer to an internal target become one-hop indirect (their “refid” attributes are directly set to the internal target’s “id”). References which indirectly refer to an internal target become direct internal references:

   <target id="id1" name="final target">
   <paragraph>
       <reference refid="id1">
           indirect internal
   <target id="id2" name="indirect internal 2" refid="id1">
   <target id="id3" name="indirect internal" refid="id1">
   

default_priority = 460

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

apply()

Override to apply the transform to the document tree.

resolve_indirect_target(target)

nonexistent_indirect_target(target)

circular_indirect_reference(target)

indirect_target_error(target, explanation)

resolve_indirect_references(target)

class ExternalTargets(document, startnode=None)

Bases: Transform

Given:

<paragraph>
    <reference refname="direct external">
        direct external
<target id="id1" name="direct external" refuri="http://direct">

The “refname” attribute is replaced by the direct “refuri” attribute:

<paragraph>
    <reference refuri="http://direct">
        direct external
<target id="id1" name="direct external" refuri="http://direct">

default_priority = 640

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

apply()

Override to apply the transform to the document tree.

class InternalTargets(document, startnode=None)

Bases: Transform

default_priority = 660

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

apply()

Override to apply the transform to the document tree.

resolve_reference_ids(target)

Given:

<paragraph>
    <reference refname="direct internal">
        direct internal
<target id="id1" name="direct internal">

The “refname” attribute is replaced by “refid” linking to the target’s “id”:

<paragraph>
    <reference refid="id1">
        direct internal
<target id="id1" name="direct internal">

class Footnotes(document, startnode=None)

Bases: Transform

Assign numbers to autonumbered footnotes, and resolve links to footnotes, citations, and their references.

Given the following document as input:

<document>
    <paragraph>
        A labeled autonumbered footnote reference:
        <footnote_reference auto="1" id="id1" refname="footnote">
    <paragraph>
        An unlabeled autonumbered footnote reference:
        <footnote_reference auto="1" id="id2">
    <footnote auto="1" id="id3">
        <paragraph>
            Unlabeled autonumbered footnote.
    <footnote auto="1" id="footnote" name="footnote">
        <paragraph>
            Labeled autonumbered footnote.

Auto-numbered footnotes have attribute auto="1" and no label. Auto-numbered footnote_references have no reference text (they’re empty elements). When resolving the numbering, a label element is added to the beginning of the footnote, and reference text to the footnote_reference.

The transformed result will be:

<document>
    <paragraph>
        A labeled autonumbered footnote reference:
        <footnote_reference auto="1" id="id1" refid="footnote">
            2
    <paragraph>
        An unlabeled autonumbered footnote reference:
        <footnote_reference auto="1" id="id2" refid="id3">
            1
    <footnote auto="1" id="id3" backrefs="id2">
        <label>
            1
        <paragraph>
            Unlabeled autonumbered footnote.
    <footnote auto="1" id="footnote" name="footnote" backrefs="id1">
        <label>
            2
        <paragraph>
            Labeled autonumbered footnote.

Note that the footnotes are not in the same order as the references.

The labels and reference text are added to the auto-numbered footnote and footnote_reference elements. Footnote elements are backlinked to their references via “refids” attributes. References are assigned “id” and “refid” attributes.

After adding labels and reference text, the “auto” attributes can be ignored.

default_priority = 620

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

autofootnote_labels = None

Keep track of unlabeled autonumbered footnotes.

symbols = ['*', '†', '‡', '§', '¶', '#', '♠', '♥', '♦', '♣']

apply()

Override to apply the transform to the document tree.

number_footnotes(startnum)

Assign numbers to autonumbered footnotes.

For labeled autonumbered footnotes, copy the number over to corresponding footnote references.

number_footnote_references(startnum)

Assign numbers to autonumbered footnote references.

symbolize_footnotes()

Add symbols indexes to “[*]”-style footnotes and references.

resolve_footnotes_and_citations()

Link manually-labeled footnotes and citations to/from their references.

resolve_references(note, reflist)

exception CircularSubstitutionDefinitionError

Bases: Exception

class Substitutions(document, startnode=None)

Bases: Transform

Given the following document as input:

<document>
    <paragraph>
        The
        <substitution_reference refname="biohazard">
            biohazard
         symbol is deservedly scary-looking.
    <substitution_definition name="biohazard">
        <image alt="biohazard" uri="biohazard.png">

The substitution_reference will simply be replaced by the contents of the corresponding substitution_definition.

The transformed result will be:

<document>
    <paragraph>
        The
        <image alt="biohazard" uri="biohazard.png">
         symbol is deservedly scary-looking.
    <substitution_definition name="biohazard">
        <image alt="biohazard" uri="biohazard.png">

default_priority = 220

The Substitutions transform has to be applied very early, before docutils.transforms.frontmatter.DocTitle and others.

apply()

Override to apply the transform to the document tree.

class TargetNotes(document, startnode)

Bases: Transform

Creates a footnote for each external target in the text, and corresponding footnote references after each reference.

default_priority = 540

The TargetNotes transform has to be applied after IndirectHyperlinks but before Footnotes.

apply()

Override to apply the transform to the document tree.

make_target_footnote(refuri, refs, notes)

class DanglingReferences(document, startnode=None)

Bases: Transform

Check for dangling references (incl. footnote & citation) and for unreferenced targets.

default_priority = 850

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

apply()

Override to apply the transform to the document tree.

class DanglingReferencesVisitor(document, unknown_reference_resolvers)

Bases: SparseNodeVisitor

unknown_visit(node)

Called when entering unknown Node types.

Raise an exception unless overridden.

visit_reference(node)

visit_footnote_reference(node)

visit_citation_reference(node)