birdnotes.py: Objects to represent bird note files

This method converts a floc node into a new Sighting instance and adds it as the next child of self.

The content of the floc element is the single-sighting pattern; refer to the schema for the relevant definitions.

# - - -   B i r d F o r m . r e a d F l o c

    def readFloc(self, flocNode, dayNotes):
        """Read one floc element.

          [ (flocNode is an rnc.FLOC_N node as an et.Element) and
            (dayNotes is a DayNotes instance) ->
              self  :=  self with a Sighting instance added, made
                        from flocNode, with parent dayNotes ]
        """

First we construct a Sighting to hold the content. See Section 13.1, “Sighting.__init__()”.

        #-- 1 --
        # [ sighting  :=  a new, empty Sighting instance with
        #                 self as its parent ]
        sighting = Sighting(self)

Next we check for the various types of content that can occur in a floc element: age-sex-group, loc-group, and sighting-notes. See Section 15.2, “AgeSexGroup.readNode() (static method)”, Section 14.2, “LocGroup.readNode(): Extract loc-group content”, and Section 16.5, “SightNotes.readNode() (static method)”.

        #-- 2 --
        # [ if flocNode has any age-sex-group content ->
        #     sighting.ageSexGroup  :=  an AgeSexGroup instance
        #         representing that content
        #   else ->
        #     sighting.ageSexGroup  :=  None ]
        sighting.ageSexGroup = AgeSexGroup.readNode(flocNode)

        #-- 3 --
        # [ if flocNode has any loc-group content ->
        #     sighting.locGroup  :=  a LocGroup instance
        #         representing that content
        #   else ->
        #     sighting.locGroup  :=  None ]
        sighting.locGroup = LocGroup.readNode(flocNode, dayNotes)

        #-- 4 --
        # [ if flocNode has any sighting-notes content ->
        #     sighting.sightNotes  :=  a SightNotes instance
        #         representing that content
        #   else ->
        #     sighting.sightNotes  :=  None ]
        sighting.sightNotes = SightNotes.readNode(flocNode)