birdnotes.py: Objects to represent bird note files

This method extracts from the date element all the information required to build a DayNotes instance.

# - - -   D a y N o t e s . r e a d N o d e    (static method)

    @staticmethod
    def readNode(noteSet, txny, dayNode):
        """Convert an rnc.DAY_NOTES_N node to a DayNotes instance.
        """

The region code and date come directly from dayNode. The day location code is an optional day-loc attribute.

        #-- 1 --
        # [ regionCode  :=  rnc.STATE_A attribute from dayNode
        #   date  :=  rnc.DATE_A attribute from dayNode ]
        regionCode = dayNode.attrib[rnc.STATE_A]
        date = dayNode.attrib[rnc.DATE_A]

        #-- 2 --
        # [ if dayNode has an rnc.DAY_LOC_A attribute ->
        #     dayLocCode  :=  that attribute
        #   else ->
        #     dayLocCode  :=  None ]
        try:
            dayLocCode = dayNode.attrib[rnc.DAY_LOC_A]
        except KeyError:
            dayLocCode = None

At this point we process the day-summary element using the static method Section 9.6, “DaySummary.readNode(): Convert from XML (static method)”.

        #-- 3 --
        # [ if  dayNode has a valid rnc.DAY_SUMMARY_N child
        #   element ->
        #     daySummary  :=  a new DaySummary instance made
        #                     from that child element
        #   else -> raise IOError ]
        summaryNode = dayNode.xpath(rnc.DAY_SUMMARY_N)[0]
        daySummary = DaySummary.readNode(summaryNode)

Now that we have read the day-summary element, we must be sure that the dayLocCode is defined, if it was given. See Section 9.2, “DaySummary.defaultLoc(): Return the default location” and Section 9.4, “DaySummary.lookupLoc(): Find a location by its code”.

        #-- 4 --
        # [ if dayLocCode is None ->
        #     dayLoc  :=  default location from daySummary
        #   else if dayLocCode is defined in daySummary ->
        #     dayLoc  :=  dayLocCode's location from daySummary
        #   else ->
        #     raise IOError ]
        if  dayLocCode is None:
            dayLoc = daySummary.defaultLoc()
        else:
            try:
                dayLoc = daySummary.lookupLoc(dayLocCode)
            except KeyError:
                raise IOError("%s '%s' is not defined in the "
                    "%s element." %
                    (rnc.DAY_LOC_A, dayLocCode, rnc.DAY_SUMMARY_N))

At this point, we have enough information to create the a DayNotes instance. See Section 8.10, “DayNotes.__init__(): Constructor”.

        #-- 5 --
        # [ dayNotes  :=  a new DayNotes instance with
        #       noteSet=noteSet, regionCode=regionCode, date=date,
        #       daySummary=daySummary, and dayLoc=dayLoc ]
        dayNotes = DayNotes(noteSet, regionCode, date, daySummary,
                                dayLoc)

Next we process all the form nodes and add them to self.

        #-- 6 --
        # [ if the subtree rooted in dayNode conforms to
        #   birdnotes.rnc ->
        #     self  :=  self with BirdForm objects added representing
        #               all rnc.FORM_N children of dayNode ]
        #   else ->
        #     self  :=  (anything)
        #     raise  IOError ]
        for formNode in dayNode.getiterator(rnc.FORM_N):
            #-- 6 body --
            # [ formNode is an et.Element ->
            #     if formNode roots a valid rnc.FORM_N subtree
            #     in the context of txny ->
            #       dayNotes  :=  dayNotes with a BirdForm object added
            #                 representing formNode
            #     else -> raise IOError ]
            BirdForm.readNode(txny, dayNotes, formNode)

Finally, return the new instance.

        #-- 7 --
        return dayNotes