|  |
| |
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:
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
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.
.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.
.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.
.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.
.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.
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 = []