Next / Previous / Contents / Shipman's homepage

7. class BirdNoteSet: One file's worth of notes

This is the principal exterior interface. An instance of this class is a container for one NOTE_SET_N node, the root element of a file conforming to birdnotes.rnc. See the definition of note-set in the schema.

This object is used in two different contexts:

Because of these differing roles, the class can both read its input from XML files, and write its contents back to an XML file. The author prefers to avoid using the features of the XML DOM (Document Object Model) that allow in-place modification of a document tree. This puts the burden of moving around the tree on the user. A better solution is to use a natural Python data structure, and write it out as XML without reference to the logic that can read XML.

Here is the class declaration and exported interface:

birdnotes.py
# - - - - -   c l a s s   B i r d N o t e S e t

class BirdNoteSet:
    """Represents a NOTE_SET_N element.

      Exports:
        BirdNoteSet(txny):
          [ (txny is a taxonomy as an xnomo3.Txny object) and
            (period is the set's period title as a string) ->
              return a new, empty BirdNoteSet using that taxonomy ]
        .txny:          [ as passed to constructor, read-only ]
        .newestTime:
          [ modification epoch time of the most recently
            modified source file read, or None ]
        .period:
          [ the set's period title, initially "", read/write ]

The constructor requires the txny object so that it can translate bird codes into their names and taxonomic positions.

The .newestTime attribute keeps track of the modification time of the most recently modified source file read into this instance. This is used by the noteweb application to avoid rebuilding XHTML files whose inputs have not changed.

The .period attribute is initially empty. If the note set is being read from a file, the .readFile() method will take care of setting it from the input file. If the note set is being created by a GUI, that application will get the period name from the user.

Here are the exported attributes and methods of the class. The .genDays() method is used to retrieve the stored records by generating a sequence of DayNotes objects.

birdnotes.py
        .genDays():
          [ generate the daily sets in self as DayNotes objects ]

For file creation through a GUI, the .addDay() method appends a new DayNotes object to the contents.

birdnotes.py
        .addDay(dayNotes):
          [ dayNotes is a DayNotes object ->
              self  :=  self with dayNotes added ]

The .readFile() method parses an XML file and, assuming it conforms to birdnotes.rnc, adds the contents of that file to the instance.

birdnotes.py
        .readFile(fileName):
          [ fileName is a string ->
              if fileName names a readable file that validates
              against birdnotes.rnc ->
                self  :=  self with the contents of that file
                          added
              else -> raise IOError ]

The .writeFile() method creates an entire new XML file representing the instance. By default, records remain in the order each form was added; specify byPhylo=True to get the records in phylogenetic order.

birdnotes.py
        .writeFile(fileName, byPhylo=False):
          [ fileName is a string ->
              if fileName names a file that can be created ->
                if byPhylo ->
                  that file  :=  contents of self with forms in
                      phylogenetic order
                else ->
                  that file  :=  contents of self with forms in
                      the order they were added
              else -> raise IOError ]

The instance contains a private attribute ._dayList that holds the DayNotes elements comprising the content of the instance.

birdnotes.py
      State/Invariants:
        ._dayList:
          [ a list containing self's daily sets as DayNotes
            objects ]
    """

7.1. BirdNoteSet.__init__(): Constructor

The constructor needs only to store its argument and set up the initial state items. The ._dayList is initialized as an empty list.

birdnotes.py
# - - -   B i r d N o t e S e t . _ _ i n i t _ _

    def __init__(self, txny):
        """Constructor for BirdNoteSet
        """
        self.txny = txny
        self.period = ""
        self.newestTime = None
        self._dayList = []