birdnotes.py: Objects to represent bird note files

# - - -   D a y S u m m a r y . r e a d N o d e

    @staticmethod
    def readNode(node):
        """Convert from XML.
        """

The default-loc attribute is required, and its value is all we need to create a new DaySummary instance. See Section 9.1, “DaySummary.__init__()”.

        #-- 1 --
        # [ defaultLocCode  :=  node's rnc.DEFAULT_LOC_A
        #                       attribute ]
        defaultLocCode = node.attrib[rnc.DEFAULT_LOC_A]

        #-- 2 --
        # [ daySummary  :=  a new DaySummary instance for
        #       default location code (defaultLocCode) ]
        daySummary = DaySummary(defaultLocCode)

Direct children of a day-summary element must start with one or more loc children, followed by the various day-annotation elements in no particular order. We'll use XPath expressions to corral and process these children. First, the loc children.

        #-- 3 --
        # [ locNodeList  :=  rnc.LOC_N children of node ]
        locNodeList = node.xpath(rnc.LOC_N)

See Section 10.4, “Loc.readNode(): Convert from XML (static method)” and Section 9.3, “DaySummary.addLoc(): Add a location definition”.

        #-- 4 --
        # [ daySummary  :=  daySummary with locations added
        #       from elements of locNodeList ]
        for  locNode in locNodeList:
            #-- 4 body --
            # [ locNode is an rnc.LOC_N node ->
            #       self  :=  self with a location added made
            #                 from locNode ]
            loc = Loc.readNode(locNode)
            daySummary.addLoc(loc)

Finally, we look for the various other child nodes. See Section 9.7, “DaySummary.dayAnnotation(): Process day-annotation content”.

        #-- 5 --
        # [ daySummary  :=  daySummary with information added from
        #       any day-annotation children of (node) ]
        daySummary.dayAnnotation(node)

Now that we have read all the definitions of today's location codes, we must perform an important validity check: there must be a definition for the default location code. If that succeeds, we're done, and can return the new DaySummary instance to the caller. See Section 9.4, “DaySummary.lookupLoc(): Find a location by its code”.

        #-- 6 --
        # [ if defaultLocCode is a valid location code in
        #   self ->
        #     I
        #   else ->
        #     raise IOError ]
        try:
            test = daySummary.lookupLoc(defaultLocCode)
        except KeyError:
            raise IOError("Default location code '%s' is not "
                "defined." % defaultLocCode)

        #-- 7 --
        return  daySummary