birdnotes.py: Objects to represent bird note files

This method looks in a given node for any of the content from the sighting-notes pattern. For the definition of the sighting-notes pattern, see the specification. Basically, we are looking for a set of items such as desc that can occur only once, and another set of items such as photo that can occur any number of times.

# - - -   S i g h t N o t e s . r e a d N o d e

    @staticmethod
    def readNode(node):
        """Extract sighting-tones from node, if any.
        """

See Section 16.1, “SightNotes.__init__()”.

        #-- 1 --
        # [ sightNotes  :=  a new, empty SightNotes instance ]
        sightNotes = SightNotes()

The processing of the narrative content in each of the potential children is done by Section 18.8, “Narrative.readChild() (static method)”.

        #-- 2 --
        # [ if node has an rnc.DESC_N child ->
        #     sightNotes.desc  :=  the narrative content of that
        #         child as a Narrative instance
        #   else ->
        #     sightNotes.desc  :=  None ]
        sightNotes.desc = Narrative.readChild(node, rnc.DESC_N)

        #-- 3 --
        # [ if node has an rnc.BEHAVIOR_N child ->
        #    sightNotes.behavior  :=  the narrative content of
        #        that child as a Narrative instance
        #   else ->
        #    sightNotes.behavior  :=  None ]
        sightNotes.behavior = Narrative.readChild(node,
            rnc.BEHAVIOR_N)

        #-- 4 --
        # [ if node has an rnc.VOC_N child ->
        #    sightNotes.voc  :=  the narrative content of
        #        that child as a Narrative instance
        #   else ->
        #    sightNotes.voc  :=  None ]
        sightNotes.voc = Narrative.readChild(node, rnc.VOC_N)

        #-- 5 --
        # [ if node has an rnc.BREEDING_N child ->
        #    sightNotes.breeding  :=  the narrative content of
        #        that child as a Narrative instance
        #   else ->
        #    sightNotes.breeding  :=  None ]
        sightNotes.breeding = Narrative.readChild(node,
            rnc.BREEDING_N)

There can be multiple photo children. See Section 17.2, “Photo.readNode() (static method)” and SightNotes-addPhoto.

        #-- 6 --
        # [ if node has any rnc.PHOTO_N children ->
        #    sightNotes  :=  sightNotes with Photo instances
        #        added representing those children
        #   else -> I ]
        photoNodeList = node.xpath(rnc.PHOTO_N)
        for  photoNode in photoNodeList:
            photo = Photo.readNode(photoNode)
            sightNotes.addPhoto(photo)

There can also be any number of para children, but we will pack them all into a Narrative instance and store that in the .notes attribute. See Section 18.1, “Narrative.__init__(): Constructor”, Section 19.7, “Paragraph.readNode(): Process a para element (static method)”, and Section 18.2, “Narrative.addPara(): Add a paragraph”.

        #-- 7 --
        # [ if node has any rnc.PARA_N children ->
        #     sightNotes.notes  :=  a new Narrative instance
        #         representing all those children
        #   else -> I ]
        paraNodeList = node.xpath(rnc.PARA_N)
        sightNotes.notes = Narrative()
        for  paraNode in paraNodeList:
            # Just because you're paraNode doesn't mean they're
            # not out to get you.
            para = Paragraph.readNode(paraNode)
            sightNotes.notes.addPara(para)

        #-- 8 --
        return sightNotes