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)

    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 8.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 8.2, “DaySummary.defaultLoc(): Return the default location” and Section 8.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 7.7, “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 ->
            #       self  :=  self with a BirdForm object added
            #                 representing formNode
            #     else -> raise IOError ]
            dayNotes.readForm ( txny, formNode )

Finally, return the new instance.

        #-- 7 --
        return dayNotes

    readNode  =  staticmethod ( readNode )