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 18.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 14.1, “LocGroup.__init__()”.

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