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 15.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 17.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 16.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 17.1, “Narrative.__init__(): Constructor”, Section 18.7, “Paragraph.readNode(): Process a para element (static method)”, and Section 17.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

    readNode  =  staticmethod(readNode)