birdnotes.py: Objects to represent bird note files

This method adds one BirdForm object to a DayNotes object. Each such object added over the life of the instance is indexed in the self._seqMap directory with a unique serial number; self._numberAdded keeps track of the number of entries added so far.

We also add the new BirdForm object to the self._txMap dictionary, with its proper two-part key.

# - - -   D a y N o t e s . a d d F o r m

    def addForm(self, newForm):
        """Add a new BirdForm object to self.
        """

First we increment self._numberAdded to account for the newly added form object, and remember the sequence number (counting from one) in the local variable seqNo.

        #-- 1 --
        # [ seqNo  :=  self._numberAdded + 1
        #   self._numberAdded  +:=  1 ]
        self._numberAdded  +=  1
        seqNo = self._numberAdded

Next, we build the two-tuple used as a key in self._txMap: see Section 3.1, “phylo-key” and Section 8.7, “DayNotes._phyloKey()”. Duplicate phylogenetic keys are disallowed starting in March 2013 because it would break the new byPhylo argument to .writeNode().

        #-- 2 --
        # [ phyloKey  :=  phylo-key(newForm.birdId) ]
        phyloKey = self._phyloKey(newForm.birdId)
        if phyloKey in self._txMap:
            raise KeyError("{0}: Duplicate entries for {1}".format(
                self.date, str(newForm.birdId)))

Then we add the new form object to the two internal dictionaries.

        #-- 2 --
        self._seqMap[seqNo] = self._txMap[phyloKey] = newForm