This is the principal exterior interface. An instance of
this class is a container for one
node, the root element of a file conforming to
See the definition of
note-set in the schema.
This object is used in two different contexts:
It can be used to read an existing notes file.
It can be used as the back end for a graphical user interface application that allows creation of new notes files, or editing of existing notes files.
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:
# - - - - - 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
.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.
.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
Here are the exported attributes and methods of the class.
.genDays() method is used to retrieve
the stored records by generating a sequence of
.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
.addDay(dayNotes): [ dayNotes is a DayNotes object -> self := self with dayNotes added ]
.readFile() method parses an XML file
and, assuming it conforms to
birdnotes.rnc, adds the contents of
that file to the instance.
.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 ]
.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
.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
elements comprising the content of the instance.
State/Invariants: ._dayList: [ a list containing self's daily sets as DayNotes objects ] """
The constructor needs only to store its argument and set
up the initial state items. The
._dayList is initialized as an empty list.
# - - - 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 =