birdnotes.py: Objects to represent bird note files

An instance of this class represents one para element: plain text, optionally interspersed with text wrapped in any of the elements in the para-markup pattern.

This implementation was originally designed to handle just two kinds of markup: genus for scientific names to be italicized, and cite for literature citations.

Hence, this implementation assumes that we can represent the content as a sequence of text strings, some of which are enclosed in markup, and some or not. In Python terms, we will store the content in the class's ._phraseList attribute as a list of tuples (tag, text) where the tag will be either the name of the markup tag, or None for text not enclosed in markup.

# - - - - -   c l a s s   P a r a g r a p h

class Paragraph:
    """Represents one paragraph of mixed content.

      Exports:
        Paragraph():
          [ return a new, empty Paragraph instance ]
        .addContent(tag, text):
          [ tag is the wrapper element's name as a string,
            or None if the text is not wrapped ->
              self  :=  self with text added, wrapped in tag
                        if there is one ]
        .getContent():
          [ generate the content in self as a sequence of
            (tag, text) tuples as in the arguments to .addContent ]
        .writeNode(parent):
          [ parent is an et.Element ->
              parent  :=  parent with content added representing
                          self ]

This class will export the usual .readNode() static method for converting a para node as an et.Element into a Paragraph instance. However, the schema's narrative pattern also allows a number of elements (such as route and desc) to have mixed content, as if it that content were wrapped in a para element. In that case, call this static method using the parent node as an argument, as if it were a para node.

        Paragraph.readNode(node):
          [ node is an et.Element containing para-content ->
              return a new Paragraph instance representing
              that content ]
     State/Invariants:
       ._phraseList:
         [ self's content as a list of tuples (tag, text)
           where tag is None for untagged text, or the
           enclosing element if tagged ]
   """

# - - -   P a r a g r a p h . _ _ i n i t _ _

    def __init__(self):
        """Constructor for Paragraph.
        """
        self._phraseList = []