birdnotes.py: Objects to represent bird note files

This method finds content in and under a given node that matches the loc-group pattern in the schema. If that content includes a loc attribute, we will also check to make sure that location code has been defined; this is why the method requires a DayNotes instance that contains the location code definitions.

# - - -   L o c G r o u p . r e a d N o d e

#   @staticmethod
    def readNode ( node, dayNotes ):
        """Extract loc-group content from a node.
        """

First we look for a loc attribute and, if it is present, also make sure it is defined for that day. If not, we set loc to None.

        #-- 1 --
        # [ if node has an rnc.LOC_A attribute defined in dayNotes ->
        #     locCode  :=  that attribute
        #   else if node has an rnc.LOC_A attribute not defined in
        #   dayNotes ->
        #     raise IOError
        #   else ->
        #     locCode  :=  None ]
        locCode  =  node.attrib.get ( rnc.LOC_A, None )

        #-- 2 --
        # [ if dayNotes has a definition for location code locCode ->
        #     loc  :=  that definition as a Loc instance
        #   else ->
        #     loc  :=  None ]
        if  locCode is not None:
            try:
                loc  =  dayNotes.lookupLoc ( locCode )
            except KeyError:
                raise IOError, ( "Location code '%s' is used but "
                    "not defined for date %s." %
                    (locCode, dayNotes.date) )
        else:
            loc  =  None

Similarly, we try to get the gps attribute, and default its value to None.

        #-- 2 -
        # [ gps  :=  node's rnc.GPS_A attribute, default None ]
        gps  =  node.attrib.get ( rnc.GPS_A, None )

If the node has a loc-detail child, we retrieve the content of the child as a Narrative instance. See Section 17.7, “Narrative.readNode(): Read XML (static method)”.

        #-- 2 --
        # [ if node has an rnc.LOC_DETAIL_N child ->
        #     locDetail  :=  the content of that child as a
        #                    Narrative instance
        #   else ->
        #     locDetail  :=  None ]
        detailChildList  =  node.xpath ( rnc.LOC_DETAIL_N )
        if  len(detailChildList) > 0:
            locDetail  =  Narrative.readNode ( detailChildList[0] )
        else:
            locDetail  =  None

At this point, if none of these three items exist, we can return None to the caller. Otherwise we box them up into a LocGroup instance and return that. See Section 13.1, “LocGroup.__init__()”.

        #-- 3 --
        if (loc or gps or locDetail):
            return LocGroup ( loc, gps, locDetail )
        else:
            return None

    readNode  =  staticmethod ( readNode )