birdnotes.py: Objects to represent bird note files

Use this method to convert an XML file conforming to birdnotes.rnc into a BirdNoteSet object. For the relevant part of the schema, see the specification.

# - - -   B i r d N o t e S e t . r e a d F i l e

    def readFile ( self, fileName ):
        """Read content from an XML file.
        """

We need to keep track of the most recently modified input file read; see Section 6.5, “BirdNoteSet.__fileTime(): Update the most recent modification time”.

        #-- 1 --
        # [ if fileName does not exist ->
        #     raise IOError
        #   else if (self.newestTime is None) or
        #   (self.newestTime < modification time of fileName) ->
        #     self.newestTime  :=  modification time of fileName
        #   else -> I ]
        self.__fileTime ( fileName )

For the logic that reads and validates the XML file, see Section 6.6, “BirdNoteSet.__validate(): Open and validate the file”.

        #-- 2 --
        # [ if fileName names a readable, well-formed XML file
        #   that validates against SCHEMA_RNG ->
        #     noteSet  :=  the root element of that tree
        #   else ->
        #     raise IOError ]
        noteSet  =  self.__validate ( fileName )

The root node's period attribute is required.

        #-- 3 --
        # [ if noteSet has an rnc.PERIOD_A attribute ->
        #     self.period  :=  that attribute
        #   else -> raise IOError ]
        try:
            self.period  =  noteSet.attrib[rnc.PERIOD_A]
        except KeyError:
            raise IOError, ( "The %s element must have a %s "
                "attribute" % 
                (rnc.NOTE_SET_N, rnc.PERIOD_A) )

All that remains is to process all the DAY_NOTES_N elements.

        #-- 4 --
        # [ dayList  :=  list of DAY_NOTES_N children of noteSet ]
        dayList  =  noteSet.xpath ( rnc.DAY_NOTES_N )

See Section 6.7, “BirdNoteSet.__readDayNotes(): Read one day-notes node”.

        #-- 5 --
        # [ self  :=  self with content added from all nodes
        #             in dayList ]
        for  node in dayList:
            self.__readDayNotes ( node )