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 7.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 7.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 8.12, “DayNotes.readNode(): XML to internal form”.

        #-- 5 --
        # [ self  :=  self with content added from all nodes
        #             in dayList ]
        for  node in dayList:
            #-- 5 body
            # [ node is a DAY_NOTES_N node ->
            #     self  :=  self with content added from node ]
            DayNotes.readNode(self, self.txny, node)