birdnotes.py: Objects to represent bird note files

This class is a container for all the content that can occur in the sighting-notes pattern in the schema. For the actual definition of this pattern, see its definition in the schema.

Writeable instance attributes are used for the items that can occur singly. For example, the .desc attribute is initially None; if there is a description, it is stored by code outside the class into that attribute as a Narrative instance. For content such as Photo that can occur any number of times, we provide methods to add these items.

# - - - - -   c l a s s   S i g h t N o t e s

class SightNotes:
    """Represents content from the sighting-notes pattern.

      Exports:
        SightNotes():
          [ return a new, empty SightNotes instance ]
        .desc:  [ description as a Narrative or None, read/write ]
        .behavior:
          [ behavior as a Narrative or None, read/write ]
        .voc:
          [ vocalizations as a Narrative or None, read/write ]
        .breeding:
          [ breeding evidence as a Narrative or None, read/write ]
        .addPhoto(photo):
          [ photo is a Photo instance ->
              self  :=  self with photo added ]
        .genPhotos():
          [ generate photos in self as a sequence of Photo instances ]
        .addPara(para):
          [ para is a Paragraph instance ->
              self  :=  self with para added to its general notes ]
        .notes:
          [ self's general notes as a Narrative instance ]

The class also has the usual functions for reading and writing XML.

        SightNotes.readNode(node):   # Static
          [ node is an et.Element ->
              if node has any sighting-notes content ->
                return a new SightNotes instance with that content
              else -> return None ]
        .writeNode(parent):
          [ parent is an et.Element ->
              parent  :=  parent with content added representing
                          self ]

      State/Invariants:
        ._photoList:
          [ list of Photo instances in the order they were added ]
    """

# - - -   S i g h t N o t e s . _ _ i n i t _ _

    def __init__(self):
        """Constructor for SightNotes
        """
        self.desc = None
        self.behavior = None
        self.voc = None
        self.breeding = None
        self.notes = None
        self._photoList = []