1 # $Id: nodes.py 5033 2007-03-21 19:51:22Z wiemann $

     2 # Author: David Goodger <goodger@python.org>

     3 # Copyright: This module has been placed in the public domain.

     4 

     5 """

     6 Docutils document tree element class library.

     7 

     8 Classes in CamelCase are abstract base classes or auxiliary classes. The one

     9 exception is `Text`, for a text (PCDATA) node; uppercase is used to

    10 differentiate from element classes.  Classes in lower_case_with_underscores

    11 are element classes, matching the XML element generic identifiers in the DTD_.

    12 

    13 The position of each node (the level at which it can occur) is significant and

    14 is represented by abstract base classes (`Root`, `Structural`, `Body`,

    15 `Inline`, etc.).  Certain transformations will be easier because we can use

    16 ``isinstance(node, base_class)`` to determine the position of the node in the

    17 hierarchy.

    18 

    19 .. _DTD: http://docutils.sourceforge.net/docs/ref/docutils.dtd

    20 """

    21 

    22 __docformat__ = 'reStructuredText'

    23 

    24 import sys

    25 import os

    26 import re

    27 import warnings

    28 from types import IntType, SliceType, StringType, UnicodeType, \

    29      TupleType, ListType, ClassType, TypeType

    30 from UserString import UserString

    31 

    32 

    33 # ==============================

    34 #  Functional Node Base Classes

    35 # ==============================

    36 

    37 class Node:

    38 

    39     """Abstract base class of nodes in a document tree."""

    40 

    41     parent = None

    42     """Back-reference to the Node immediately containing this Node."""

    43 

    44     document = None

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

    46 

    47     source = None

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

    49 

    50     line = None

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

    52 

    53     def __nonzero__(self):

    54         """

    55         Node instances are always true, even if they're empty.  A node is more

    56         than a simple container.  Its boolean "truth" does not depend on

    57         having one or more subnodes in the doctree.

    58 

    59         Use `len()` to check node length.  Use `None` to represent a boolean

    60         false value.

    61         """

    62         return 1

    63 

    64     def __str__(self):

    65         return self.__unicode__().encode('raw_unicode_escape')

    66 

    67     def __unicode__(self):

    68         # Override in subclass.

    69         raise NotImplementedError

    70 

    71     def asdom(self, dom=None):

    72         """Return a DOM **fragment** representation of this Node."""

    73         if dom is None:

    74             import xml.dom.minidom as dom

    75         domroot = dom.Document()

    76         return self._dom_node(domroot)

    77 

    78     def pformat(self, indent='    ', level=0):

    79         """

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

    81 

    82         Override in subclasses.

    83         """

    84         raise NotImplementedError

    85 

    86     def copy(self):

    87         """Return a copy of self."""

    88         raise NotImplementedError

    89 

    90     def deepcopy(self):

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

    92         raise NotImplementedError

    93 

    94     def setup_child(self, child):

    95         child.parent = self

    96         if self.document:

    97             child.document = self.document

    98             if child.source is None:

    99                 child.source = self.document.current_source

   100             if child.line is None:

   101                 child.line = self.document.current_line

   102 

   103     def walk(self, visitor):

   104         """

   105         Traverse a tree of `Node` objects, calling the

   106         `dispatch_visit()` method of `visitor` when entering each

   107         node.  (The `walkabout()` method is similar, except it also

   108         calls the `dispatch_departure()` method before exiting each

   109         node.)

   110 

   111         This tree traversal supports limited in-place tree

   112         modifications.  Replacing one node with one or more nodes is

   113         OK, as is removing an element.  However, if the node removed

   114         or replaced occurs after the current node, the old node will

   115         still be traversed, and any new nodes will not.

   116 

   117         Within ``visit`` methods (and ``depart`` methods for

   118         `walkabout()`), `TreePruningException` subclasses may be raised

   119         (`SkipChildren`, `SkipSiblings`, `SkipNode`, `SkipDeparture`).

   120 

   121         Parameter `visitor`: A `NodeVisitor` object, containing a

   122         ``visit`` implementation for each `Node` subclass encountered.

   123 

   124         Return true if we should stop the traversal.

   125         """

   126         stop = 0

   127         visitor.document.reporter.debug(

   128             'docutils.nodes.Node.walk calling dispatch_visit for %s'

   129             % self.__class__.__name__)

   130         try:

   131             try:

   132                 visitor.dispatch_visit(self)

   133             except (SkipChildren, SkipNode):

   134                 return stop

   135             except SkipDeparture:           # not applicable; ignore

   136                 pass

   137             children = self.children

   138             try:

   139                 for child in children[:]:

   140                     if child.walk(visitor):

   141                         stop = 1

   142                         break

   143             except SkipSiblings:

   144                 pass

   145         except StopTraversal:

   146             stop = 1

   147         return stop

   148 

   149     def walkabout(self, visitor):

   150         """

   151         Perform a tree traversal similarly to `Node.walk()` (which

   152         see), except also call the `dispatch_departure()` method

   153         before exiting each node.

   154 

   155         Parameter `visitor`: A `NodeVisitor` object, containing a

   156         ``visit`` and ``depart`` implementation for each `Node`

   157         subclass encountered.

   158 

   159         Return true if we should stop the traversal.

   160         """

   161         call_depart = 1

   162         stop = 0

   163         visitor.document.reporter.debug(

   164             'docutils.nodes.Node.walkabout calling dispatch_visit for %s'

   165             % self.__class__.__name__)

   166         try:

   167             try:

   168                 visitor.dispatch_visit(self)

   169             except SkipNode:

   170                 return stop

   171             except SkipDeparture:

   172                 call_depart = 0

   173             children = self.children

   174             try:

   175                 for child in children[:]:

   176                     if child.walkabout(visitor):

   177                         stop = 1

   178                         break

   179             except SkipSiblings:

   180                 pass

   181         except SkipChildren:

   182             pass

   183         except StopTraversal:

   184             stop = 1

   185         if call_depart:

   186             visitor.document.reporter.debug(

   187                 'docutils.nodes.Node.walkabout calling dispatch_departure '

   188                 'for %s' % self.__class__.__name__)

   189             visitor.dispatch_departure(self)

   190         return stop

   191 

   192     def traverse(self, condition=None,

   193                  include_self=1, descend=1, siblings=0, ascend=0):

   194         """

   195         Return an iterable containing

   196 

   197         * self (if include_self is true)

   198         * all descendants in tree traversal order (if descend is true)

   199         * all siblings (if siblings is true) and their descendants (if

   200           also descend is true)

   201         * the siblings of the parent (if ascend is true) and their

   202           descendants (if also descend is true), and so on

   203 

   204         If `condition` is not None, the iterable contains only nodes

   205         for which ``condition(node)`` is true.  If `condition` is a

   206         node class ``cls``, it is equivalent to a function consisting

   207         of ``return isinstance(node, cls)``.

   208 

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

   210 

   211         For example, given the following tree::

   212 

   213             <paragraph>

   214                 <emphasis>      <--- emphasis.traverse() and

   215                     <strong>    <--- strong.traverse() are called.

   216                         Foo

   217                     Bar

   218                 <reference name="Baz" refid="baz">

   219                     Baz

   220 

   221         Then list(emphasis.traverse()) equals ::

   222 

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

   224 

   225         and list(strong.traverse(ascend=1)) equals ::

   226 

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

   228         """

   229         r = []

   230         if ascend:

   231             siblings=1

   232         # Check if `condition` is a class (check for TypeType for Python

   233         # implementations that use only new-style classes, like PyPy).

   234         if isinstance(condition, (ClassType, TypeType)):

   235             node_class = condition

   236             def condition(node, node_class=node_class):

   237                 return isinstance(node, node_class)

   238         if include_self and (condition is None or condition(self)):

   239             r.append(self)

   240         if descend and len(self.children):

   241             for child in self:

   242                 r.extend(child.traverse(

   243                     include_self=1, descend=1, siblings=0, ascend=0,

   244                     condition=condition))

   245         if siblings or ascend:

   246             node = self

   247             while node.parent:

   248                 index = node.parent.index(node)

   249                 for sibling in node.parent[index+1:]:

   250                     r.extend(sibling.traverse(include_self=1, descend=descend,

   251                                               siblings=0, ascend=0,

   252                                               condition=condition))

   253                 if not ascend:

   254                     break

   255                 else:

   256                     node = node.parent

   257         return r

   258 

   259     def next_node(self, condition=None,

   260                   include_self=0, descend=1, siblings=0, ascend=0):

   261         """

   262         Return the first node in the iterable returned by traverse(),

   263         or None if the iterable is empty.

   264 

   265         Parameter list is the same as of traverse.  Note that

   266         include_self defaults to 0, though.

   267         """

   268         iterable = self.traverse(condition=condition,

   269                                  include_self=include_self, descend=descend,

   270                                  siblings=siblings, ascend=ascend)

   271         try:

   272             return iterable[0]

   273         except IndexError:

   274             return None

   275 

   276 class Text(Node, UserString):

   277 

   278     """

   279     Instances are terminal nodes (leaves) containing text only; no child

   280     nodes or attributes.  Initialize by passing a string to the constructor.

   281     Access the text itself with the `astext` method.

   282     """

   283 

   284     tagname = '#text'

   285 

   286     children = ()

   287     """Text nodes have no children, and cannot have children."""

   288 

   289     def __init__(self, data, rawsource=''):

   290         UserString.__init__(self, data)

   291 

   292         self.rawsource = rawsource

   293         """The raw text from which this element was constructed."""

   294 

   295     def __repr__(self):

   296         data = repr(self.data)

   297         if len(data) > 70:

   298             data = repr(self.data[:64] + ' ...')

   299         return '<%s: %s>' % (self.tagname, data)

   300 

   301     def __len__(self):

   302         return len(self.data)

   303 

   304     def shortrepr(self):

   305         data = repr(self.data)

   306         if len(data) > 20:

   307             data = repr(self.data[:16] + ' ...')

   308         return '<%s: %s>' % (self.tagname, data)

   309 

   310     def _dom_node(self, domroot):

   311         return domroot.createTextNode(self.data)

   312 

   313     def astext(self):

   314         return self.data

   315 

   316     def __unicode__(self):

   317         return self.data

   318 

   319     def copy(self):

   320         return self.__class__(self.data)

   321 

   322     def deepcopy(self):

   323         return self.copy()

   324 

   325     def pformat(self, indent='    ', level=0):

   326         result = []

   327         indent = indent * level

   328         for line in self.data.splitlines():

   329             result.append(indent + line + '\n')

   330         return ''.join(result)

   331 

   332 

   333 class Element(Node):

   334 

   335     """

   336     `Element` is the superclass to all specific elements.

   337 

   338     Elements contain attributes and child nodes.  Elements emulate

   339     dictionaries for attributes, indexing by attribute name (a string).  To

   340     set the attribute 'att' to 'value', do::

   341 

   342         element['att'] = 'value'

   343 

   344     There are two special attributes: 'ids' and 'names'.  Both are

   345     lists of unique identifiers, and names serve as human interfaces

   346     to IDs.  Names are case- and whitespace-normalized (see the

   347     fully_normalize_name() function), and IDs conform to the regular

   348     expression ``[a-z](-?[a-z0-9]+)*`` (see the make_id() function).

   349 

   350     Elements also emulate lists for child nodes (element nodes and/or text

   351     nodes), indexing by integer.  To get the first child node, use::

   352 

   353         element[0]

   354 

   355     Elements may be constructed using the ``+=`` operator.  To add one new

   356     child node to element, do::

   357 

   358         element += node

   359 

   360     This is equivalent to ``element.append(node)``.

   361 

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

   363     operator::

   364 

   365         element += [node1, node2]

   366 

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

   368     """

   369 

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

   371     """List attributes, automatically initialized to empty lists for

   372     all nodes."""

   373 

   374     tagname = None

   375     """The element generic identifier. If None, it is set as an instance

   376     attribute to the name of the class."""

   377 

   378     child_text_separator = '\n\n'

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

   380 

   381     def __init__(self, rawsource='', *children, **attributes):

   382         self.rawsource = rawsource

   383         """The raw text from which this element was constructed."""

   384 

   385         self.children = []

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

   387 

   388         self.extend(children)           # maintain parent info

   389 

   390         self.attributes = {}

   391         """Dictionary of attribute {name: value}."""

   392 

   393         # Initialize list attributes.

   394         for att in self.list_attributes:

   395             self.attributes[att] = []

   396 

   397         for att, value in attributes.items():

   398             att = att.lower()

   399             if att in self.list_attributes:

   400                 # mutable list; make a copy for this node

   401                 self.attributes[att] = value[:]

   402             else:

   403                 self.attributes[att] = value

   404 

   405         if self.tagname is None:

   406             self.tagname = self.__class__.__name__

   407 

   408     def _dom_node(self, domroot):

   409         element = domroot.createElement(self.tagname)

   410         for attribute, value in self.attlist():

   411             if isinstance(value, ListType):

   412                 value = ' '.join([serial_escape('%s' % v) for v in value])

   413             element.setAttribute(attribute, '%s' % value)

   414         for child in self.children:

   415             element.appendChild(child._dom_node(domroot))

   416         return element

   417 

   418     def __repr__(self):

   419         data = ''

   420         for c in self.children:

   421             data += c.shortrepr()

   422             if len(data) > 60:

   423                 data = data[:56] + ' ...'

   424                 break

   425         if self['names']:

   426             return '<%s "%s": %s>' % (self.__class__.__name__,

   427                                       '; '.join(self['names']), data)

   428         else:

   429             return '<%s: %s>' % (self.__class__.__name__, data)

   430 

   431     def shortrepr(self):

   432         if self['names']:

   433             return '<%s "%s"...>' % (self.__class__.__name__,

   434                                      '; '.join(self['names']))

   435         else:

   436             return '<%s...>' % self.tagname

   437 

   438     def __unicode__(self):

   439         if self.children:

   440             return u'%s%s%s' % (self.starttag(),

   441                                 ''.join([unicode(c) for c in self.children]),

   442                                 self.endtag())

   443         else:

   444             return self.emptytag()

   445 

   446     def starttag(self):

   447         parts = [self.tagname]

   448         for name, value in self.attlist():

   449             if value is None:           # boolean attribute

   450                 parts.append(name)

   451             elif isinstance(value, ListType):

   452                 values = [serial_escape('%s' % v) for v in value]

   453                 parts.append('%s="%s"' % (name, ' '.join(values)))

   454             else:

   455                 parts.append('%s="%s"' % (name, value))

   456         return '<%s>' % ' '.join(parts)

   457 

   458     def endtag(self):

   459         return '</%s>' % self.tagname

   460 

   461     def emptytag(self):

   462         return u'<%s/>' % ' '.join([self.tagname] +

   463                                     ['%s="%s"' % (n, v)

   464                                      for n, v in self.attlist()])

   465 

   466     def __len__(self):

   467         return len(self.children)

   468 

   469     def __getitem__(self, key):

   470         if isinstance(key, UnicodeType) or isinstance(key, StringType):

   471             return self.attributes[key]

   472         elif isinstance(key, IntType):

   473             return self.children[key]

   474         elif isinstance(key, SliceType):

   475             assert key.step in (None, 1), 'cannot handle slice with stride'

   476             return self.children[key.start:key.stop]

   477         else:

   478             raise TypeError, ('element index must be an integer, a slice, or '

   479                               'an attribute name string')

   480 

   481     def __setitem__(self, key, item):

   482         if isinstance(key, UnicodeType) or isinstance(key, StringType):

   483             self.attributes[str(key)] = item

   484         elif isinstance(key, IntType):

   485             self.setup_child(item)

   486             self.children[key] = item

   487         elif isinstance(key, SliceType):

   488             assert key.step in (None, 1), 'cannot handle slice with stride'

   489             for node in item:

   490                 self.setup_child(node)

   491             self.children[key.start:key.stop] = item

   492         else:

   493             raise TypeError, ('element index must be an integer, a slice, or '

   494                               'an attribute name string')

   495 

   496     def __delitem__(self, key):

   497         if isinstance(key, UnicodeType) or isinstance(key, StringType):

   498             del self.attributes[key]

   499         elif isinstance(key, IntType):

   500             del self.children[key]

   501         elif isinstance(key, SliceType):

   502             assert key.step in (None, 1), 'cannot handle slice with stride'

   503             del self.children[key.start:key.stop]

   504         else:

   505             raise TypeError, ('element index must be an integer, a simple '

   506                               'slice, or an attribute name string')

   507 

   508     def __add__(self, other):

   509         return self.children + other

   510 

   511     def __radd__(self, other):

   512         return other + self.children

   513 

   514     def __iadd__(self, other):

   515         """Append a node or a list of nodes to `self.children`."""

   516         if isinstance(other, Node):

   517             self.append(other)

   518         elif other is not None:

   519             self.extend(other)

   520         return self

   521 

   522     def astext(self):

   523         return self.child_text_separator.join(

   524               [child.astext() for child in self.children])

   525 

   526     def non_default_attributes(self):

   527         atts = {}

   528         for key, value in self.attributes.items():

   529             if self.is_not_default(key):

   530                 atts[key] = value

   531         return atts

   532 

   533     def attlist(self):

   534         attlist = self.non_default_attributes().items()

   535         attlist.sort()

   536         return attlist

   537 

   538     def get(self, key, failobj=None):

   539         return self.attributes.get(key, failobj)

   540 

   541     def hasattr(self, attr):

   542         return self.attributes.has_key(attr)

   543 

   544     def delattr(self, attr):

   545         if self.attributes.has_key(attr):

   546             del self.attributes[attr]

   547 

   548     def setdefault(self, key, failobj=None):

   549         return self.attributes.setdefault(key, failobj)

   550 

   551     has_key = hasattr

   552 

   553     def append(self, item):

   554         self.setup_child(item)

   555         self.children.append(item)

   556 

   557     def extend(self, item):

   558         for node in item:

   559             self.append(node)

   560 

   561     def insert(self, index, item):

   562         if isinstance(item, Node):

   563             self.setup_child(item)

   564             self.children.insert(index, item)

   565         elif item is not None:

   566             self[index:index] = item

   567 

   568     def pop(self, i=-1):

   569         return self.children.pop(i)

   570 

   571     def remove(self, item):

   572         self.children.remove(item)

   573 

   574     def index(self, item):

   575         return self.children.index(item)

   576 

   577     def is_not_default(self, key):

   578         if self[key] == [] and key in self.list_attributes:

   579             return 0

   580         else:

   581             return 1

   582 

   583     def update_basic_atts(self, dict):

   584         """

   585         Update basic attributes ('ids', 'names', 'classes',

   586         'dupnames', but not 'source') from node or dictionary `dict`.

   587         """

   588         if isinstance(dict, Node):

   589             dict = dict.attributes

   590         for att in ('ids', 'classes', 'names', 'dupnames'):

   591             for value in dict.get(att, []):

   592                 if not value in self[att]:

   593                     self[att].append(value)

   594 

   595     def clear(self):

   596         self.children = []

   597 

   598     def replace(self, old, new):

   599         """Replace one child `Node` with another child or children."""

   600         index = self.index(old)

   601         if isinstance(new, Node):

   602             self.setup_child(new)

   603             self[index] = new

   604         elif new is not None:

   605             self[index:index+1] = new

   606 

   607     def replace_self(self, new):

   608         """

   609         Replace `self` node with `new`, where `new` is a node or a

   610         list of nodes.

   611         """

   612         update = new

   613         if not isinstance(new, Node):

   614             # `new` is a list; update first child.

   615             try:

   616                 update = new[0]

   617             except IndexError:

   618                 update = None

   619         if isinstance(update, Element):

   620             update.update_basic_atts(self)

   621         else:

   622             # `update` is a Text node or `new` is an empty list.

   623             # Assert that we aren't losing any attributes.

   624             for att in ('ids', 'names', 'classes', 'dupnames'):

   625                 assert not self[att], \

   626                        'Losing "%s" attribute: %s' % (att, self[att])

   627         self.parent.replace(self, new)

   628 

   629     def first_child_matching_class(self, childclass, start=0, end=sys.maxint):

   630         """

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

   632 

   633         Parameters:

   634 

   635         - `childclass`: A `Node` subclass to search for, or a tuple of `Node`

   636           classes. If a tuple, any of the classes may match.

   637         - `start`: Initial index to check.

   638         - `end`: Initial index to *not* check.

   639         """

   640         if not isinstance(childclass, TupleType):

   641             childclass = (childclass,)

   642         for index in range(start, min(len(self), end)):

   643             for c in childclass:

   644                 if isinstance(self[index], c):

   645                     return index

   646         return None

   647 

   648     def first_child_not_matching_class(self, childclass, start=0,

   649                                        end=sys.maxint):

   650         """

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

   652 

   653         Parameters:

   654 

   655         - `childclass`: A `Node` subclass to skip, or a tuple of `Node`

   656           classes. If a tuple, none of the classes may match.

   657         - `start`: Initial index to check.

   658         - `end`: Initial index to *not* check.

   659         """

   660         if not isinstance(childclass, TupleType):

   661             childclass = (childclass,)

   662         for index in range(start, min(len(self), end)):

   663             for c in childclass:

   664                 if isinstance(self.children[index], c):

   665                     break

   666             else:

   667                 return index

   668         return None

   669 

   670     def pformat(self, indent='    ', level=0):

   671         return ''.join(['%s%s\n' % (indent * level, self.starttag())] +

   672                        [child.pformat(indent, level+1)

   673                         for child in self.children])

   674 

   675     def copy(self):

   676         return self.__class__(**self.attributes)

   677 

   678     def deepcopy(self):

   679         copy = self.copy()

   680         copy.extend([child.deepcopy() for child in self.children])

   681         return copy

   682 

   683     def set_class(self, name):

   684         """Add a new class to the "classes" attribute."""

   685         warnings.warn('docutils.nodes.Element.set_class deprecated; '

   686                       "append to Element['classes'] list attribute directly",

   687                       DeprecationWarning, stacklevel=2)

   688         assert ' ' not in name

   689         self['classes'].append(name.lower())

   690 

   691     def note_referenced_by(self, name=None, id=None):

   692         """Note that this Element has been referenced by its name

   693         `name` or id `id`."""

   694         self.referenced = 1

   695         # Element.expect_referenced_by_* dictionaries map names or ids

   696         # to nodes whose ``referenced`` attribute is set to true as

   697         # soon as this node is referenced by the given name or id.

   698         # Needed for target propagation.

   699         by_name = getattr(self, 'expect_referenced_by_name', {}).get(name)

   700         by_id = getattr(self, 'expect_referenced_by_id', {}).get(id)

   701         if by_name:

   702             assert name is not None

   703             by_name.referenced = 1

   704         if by_id:

   705             assert id is not None

   706             by_id.referenced = 1

   707 

   708 

   709 class TextElement(Element):

   710 

   711     """

   712     An element which directly contains text.

   713 

   714     Its children are all `Text` or `Inline` subclass nodes.  You can

   715     check whether an element's context is inline simply by checking whether

   716     its immediate parent is a `TextElement` instance (including subclasses).

   717     This is handy for nodes like `image` that can appear both inline and as

   718     standalone body elements.

   719 

   720     If passing children to `__init__()`, make sure to set `text` to

   721     ``''`` or some other suitable value.

   722     """

   723 

   724     child_text_separator = ''

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

   726 

   727     def __init__(self, rawsource='', text='', *children, **attributes):

   728         if text != '':

   729             textnode = Text(text)

   730             Element.__init__(self, rawsource, textnode, *children,

   731                               **attributes)

   732         else:

   733             Element.__init__(self, rawsource, *children, **attributes)

   734 

   735 

   736 class FixedTextElement(TextElement):

   737 

   738     """An element which directly contains preformatted text."""

   739 

   740     def __init__(self, rawsource='', text='', *children, **attributes):

   741         TextElement.__init__(self, rawsource, text, *children, **attributes)

   742         self.attributes['xml:space'] = 'preserve'

   743 

   744 

   745 # ========

   746 #  Mixins

   747 # ========

   748 

   749 class Resolvable:

   750 

   751     resolved = 0

   752 

   753 

   754 class BackLinkable:

   755 

   756     def add_backref(self, refid):

   757         self['backrefs'].append(refid)

   758 

   759 

   760 # ====================

   761 #  Element Categories

   762 # ====================

   763 

   764 class Root: pass

   765 

   766 class Titular: pass

   767 

   768 class PreBibliographic:

   769     """Category of Node which may occur before Bibliographic Nodes."""

   770 

   771 class Bibliographic: pass

   772 

   773 class Decorative(PreBibliographic): pass

   774 

   775 class Structural: pass

   776 

   777 class Body: pass

   778 

   779 class General(Body): pass

   780 

   781 class Sequential(Body):

   782     """List-like elements."""

   783 

   784 class Admonition(Body): pass

   785 

   786 class Special(Body):

   787     """Special internal body elements."""

   788 

   789 class Invisible(PreBibliographic):

   790     """Internal elements that don't appear in output."""

   791 

   792 class Part: pass

   793 

   794 class Inline: pass

   795 

   796 class Referential(Resolvable): pass

   797 

   798 

   799 class Targetable(Resolvable):

   800 

   801     referenced = 0

   802 

   803     indirect_reference_name = None

   804     """Holds the whitespace_normalized_name (contains mixed case) of a target.

   805     Required for MoinMoin/reST compatibility."""

   806 

   807 

   808 class Labeled:

   809     """Contains a `label` as its first element."""

   810 

   811 

   812 # ==============

   813 #  Root Element

   814 # ==============

   815 

   816 class document(Root, Structural, Element):

   817 

   818     """

   819     The document root element.

   820 

   821     Do not instantiate this class directly; use

   822     `docutils.utils.new_document()` instead.

   823     """

   824 

   825     def __init__(self, settings, reporter, *args, **kwargs):

   826         Element.__init__(self, *args, **kwargs)

   827 

   828         self.current_source = None

   829         """Path to or description of the input source being processed."""

   830 

   831         self.current_line = None

   832         """Line number (1-based) of `current_source`."""

   833 

   834         self.settings = settings

   835         """Runtime settings data record."""

   836 

   837         self.reporter = reporter

   838         """System message generator."""

   839 

   840         self.indirect_targets = []

   841         """List of indirect target nodes."""

   842 

   843         self.substitution_defs = {}

   844         """Mapping of substitution names to substitution_definition nodes."""

   845 

   846         self.substitution_names = {}

   847         """Mapping of case-normalized substitution names to case-sensitive

   848         names."""

   849 

   850         self.refnames = {}

   851         """Mapping of names to lists of referencing nodes."""

   852 

   853         self.refids = {}

   854         """Mapping of ids to lists of referencing nodes."""

   855 

   856         self.nameids = {}

   857         """Mapping of names to unique id's."""

   858 

   859         self.nametypes = {}

   860         """Mapping of names to hyperlink type (boolean: True => explicit,

   861         False => implicit."""

   862 

   863         self.ids = {}

   864         """Mapping of ids to nodes."""

   865 

   866         self.footnote_refs = {}

   867         """Mapping of footnote labels to lists of footnote_reference nodes."""

   868 

   869         self.citation_refs = {}

   870         """Mapping of citation labels to lists of citation_reference nodes."""

   871 

   872         self.autofootnotes = []

   873         """List of auto-numbered footnote nodes."""

   874 

   875         self.autofootnote_refs = []

   876         """List of auto-numbered footnote_reference nodes."""

   877 

   878         self.symbol_footnotes = []

   879         """List of symbol footnote nodes."""

   880 

   881         self.symbol_footnote_refs = []

   882         """List of symbol footnote_reference nodes."""

   883 

   884         self.footnotes = []

   885         """List of manually-numbered footnote nodes."""

   886 

   887         self.citations = []

   888         """List of citation nodes."""

   889 

   890         self.autofootnote_start = 1

   891         """Initial auto-numbered footnote number."""

   892 

   893         self.symbol_footnote_start = 0

   894         """Initial symbol footnote symbol index."""

   895 

   896         self.id_start = 1

   897         """Initial ID number."""

   898 

   899         self.parse_messages = []

   900         """System messages generated while parsing."""

   901 

   902         self.transform_messages = []

   903         """System messages generated while applying transforms."""

   904 

   905         import docutils.transforms

   906         self.transformer = docutils.transforms.Transformer(self)

   907         """Storage for transforms to be applied to this document."""

   908 

   909         self.decoration = None

   910         """Document's `decoration` node."""

   911 

   912         self.document = self

   913 

   914     def __getstate__(self):

   915         """

   916         Return dict with unpicklable references removed.

   917         """

   918         state = self.__dict__.copy()

   919         state['reporter'] = None

   920         state['transformer'] = None

   921         return state

   922 

   923     def asdom(self, dom=None):

   924         """Return a DOM representation of this document."""

   925         if dom is None:

   926             import xml.dom.minidom as dom

   927         domroot = dom.Document()

   928         domroot.appendChild(self._dom_node(domroot))

   929         return domroot

   930 

   931     def set_id(self, node, msgnode=None):

   932         for id in node['ids']:

   933             if self.ids.has_key(id) and self.ids[id] is not node:

   934                 msg = self.reporter.severe('Duplicate ID: "%s".' % id)

   935                 if msgnode != None:

   936                     msgnode += msg

   937         if not node['ids']:

   938             for name in node['names']:

   939                 id = self.settings.id_prefix + make_id(name)

   940                 if id and not self.ids.has_key(id):

   941                     break

   942             else:

   943                 id = ''

   944                 while not id or self.ids.has_key(id):

   945                     id = (self.settings.id_prefix +

   946                           self.settings.auto_id_prefix + str(self.id_start))

   947                     self.id_start += 1

   948             node['ids'].append(id)

   949         self.ids[id] = node

   950         return id

   951 

   952     def set_name_id_map(self, node, id, msgnode=None, explicit=None):

   953         """

   954         `self.nameids` maps names to IDs, while `self.nametypes` maps names to

   955         booleans representing hyperlink type (True==explicit,

   956         False==implicit).  This method updates the mappings.

   957 

   958         The following state transition table shows how `self.nameids` ("ids")

   959         and `self.nametypes` ("types") change with new input (a call to this

   960         method), and what actions are performed ("implicit"-type system

   961         messages are INFO/1, and "explicit"-type system messages are ERROR/3):

   962 

   963         ====  =====  ========  ========  =======  ====  =====  =====

   964          Old State    Input          Action        New State   Notes

   965         -----------  --------  -----------------  -----------  -----

   966         ids   types  new type  sys.msg.  dupname  ids   types

   967         ====  =====  ========  ========  =======  ====  =====  =====

   968         -     -      explicit  -         -        new   True

   969         -     -      implicit  -         -        new   False

   970         None  False  explicit  -         -        new   True

   971         old   False  explicit  implicit  old      new   True

   972         None  True   explicit  explicit  new      None  True

   973         old   True   explicit  explicit  new,old  None  True   [#]_

   974         None  False  implicit  implicit  new      None  False

   975         old   False  implicit  implicit  new,old  None  False

   976         None  True   implicit  implicit  new      None  True

   977         old   True   implicit  implicit  new      old   True

   978         ====  =====  ========  ========  =======  ====  =====  =====

   979 

   980         .. [#] Do not clear the name-to-id map or invalidate the old target if

   981            both old and new targets are external and refer to identical URIs.

   982            The new target is invalidated regardless.

   983         """

   984         for name in node['names']:

   985             if self.nameids.has_key(name):

   986                 self.set_duplicate_name_id(node, id, name, msgnode, explicit)

   987             else:

   988                 self.nameids[name] = id

   989                 self.nametypes[name] = explicit

   990 

   991     def set_duplicate_name_id(self, node, id, name, msgnode, explicit):

   992         old_id = self.nameids[name]

   993         old_explicit = self.nametypes[name]

   994         self.nametypes[name] = old_explicit or explicit

   995         if explicit:

   996             if old_explicit:

   997                 level = 2

   998                 if old_id is not None:

   999                     old_node = self.ids[old_id]

  1000                     if node.has_key('refuri'):

  1001                         refuri = node['refuri']

  1002                         if old_node['names'] \

  1003                                and old_node.has_key('refuri') \

  1004                                and old_node['refuri'] == refuri:

  1005                             level = 1   # just inform if refuri's identical

  1006                     if level > 1:

  1007                         dupname(old_node, name)

  1008                         self.nameids[name] = None

  1009                 msg = self.reporter.system_message(

  1010                     level, 'Duplicate explicit target name: "%s".' % name,

  1011                     backrefs=[id], base_node=node)

  1012                 if msgnode != None:

  1013                     msgnode += msg

  1014                 dupname(node, name)

  1015             else:

  1016                 self.nameids[name] = id

  1017                 if old_id is not None:

  1018                     old_node = self.ids[old_id]

  1019                     dupname(old_node, name)

  1020         else:

  1021             if old_id is not None and not old_explicit:

  1022                 self.nameids[name] = None

  1023                 old_node = self.ids[old_id]

  1024                 dupname(old_node, name)

  1025             dupname(node, name)

  1026         if not explicit or (not old_explicit and old_id is not None):

  1027             msg = self.reporter.info(

  1028                 'Duplicate implicit target name: "%s".' % name,

  1029                 backrefs=[id], base_node=node)

  1030             if msgnode != None:

  1031                 msgnode += msg

  1032 

  1033     def has_name(self, name):

  1034         return self.nameids.has_key(name)

  1035 

  1036     # "note" here is an imperative verb: "take note of".

  1037     def note_implicit_target(self, target, msgnode=None):

  1038         id = self.set_id(target, msgnode)

  1039         self.set_name_id_map(target, id, msgnode, explicit=None)

  1040 

  1041     def note_explicit_target(self, target, msgnode=None):

  1042         id = self.set_id(target, msgnode)

  1043         self.set_name_id_map(target, id, msgnode, explicit=1)

  1044 

  1045     def note_refname(self, node):

  1046         self.refnames.setdefault(node['refname'], []).append(node)

  1047 

  1048     def note_refid(self, node):

  1049         self.refids.setdefault(node['refid'], []).append(node)

  1050 

  1051     def note_indirect_target(self, target):

  1052         self.indirect_targets.append(target)

  1053         if target['names']:

  1054             self.note_refname(target)

  1055 

  1056     def note_anonymous_target(self, target):

  1057         self.set_id(target)

  1058 

  1059     def note_autofootnote(self, footnote):

  1060         self.set_id(footnote)

  1061         self.autofootnotes.append(footnote)

  1062 

  1063     def note_autofootnote_ref(self, ref):

  1064         self.set_id(ref)

  1065         self.autofootnote_refs.append(ref)

  1066 

  1067     def note_symbol_footnote(self, footnote):

  1068         self.set_id(footnote)

  1069         self.symbol_footnotes.append(footnote)

  1070 

  1071     def note_symbol_footnote_ref(self, ref):

  1072         self.set_id(ref)

  1073         self.symbol_footnote_refs.append(ref)

  1074 

  1075     def note_footnote(self, footnote):

  1076         self.set_id(footnote)

  1077         self.footnotes.append(footnote)

  1078 

  1079     def note_footnote_ref(self, ref):

  1080         self.set_id(ref)

  1081         self.footnote_refs.setdefault(ref['refname'], []).append(ref)

  1082         self.note_refname(ref)

  1083 

  1084     def note_citation(self, citation):

  1085         self.citations.append(citation)

  1086 

  1087     def note_citation_ref(self, ref):

  1088         self.set_id(ref)

  1089         self.citation_refs.setdefault(ref['refname'], []).append(ref)

  1090         self.note_refname(ref)

  1091 

  1092     def note_substitution_def(self, subdef, def_name, msgnode=None):

  1093         name = whitespace_normalize_name(def_name)

  1094         if self.substitution_defs.has_key(name):

  1095             msg = self.reporter.error(

  1096                   'Duplicate substitution definition name: "%s".' % name,

  1097                   base_node=subdef)

  1098             if msgnode != None:

  1099                 msgnode += msg

  1100             oldnode = self.substitution_defs[name]

  1101             dupname(oldnode, name)

  1102         # keep only the last definition:

  1103         self.substitution_defs[name] = subdef

  1104         # case-insensitive mapping:

  1105         self.substitution_names[fully_normalize_name(name)] = name

  1106 

  1107     def note_substitution_ref(self, subref, refname):

  1108         subref['refname'] = whitespace_normalize_name(refname)

  1109 

  1110     def note_pending(self, pending, priority=None):

  1111         self.transformer.add_pending(pending, priority)

  1112 

  1113     def note_parse_message(self, message):

  1114         self.parse_messages.append(message)

  1115 

  1116     def note_transform_message(self, message):

  1117         self.transform_messages.append(message)

  1118 

  1119     def note_source(self, source, offset):

  1120         self.current_source = source

  1121         if offset is None:

  1122             self.current_line = offset

  1123         else:

  1124             self.current_line = offset + 1

  1125 

  1126     def copy(self):

  1127         return self.__class__(self.settings, self.reporter,

  1128                               **self.attributes)

  1129 

  1130     def get_decoration(self):

  1131         if not self.decoration:

  1132             self.decoration = decoration()

  1133             index = self.first_child_not_matching_class(Titular)

  1134             if index is None: