Bird taxonomy system: internal maintenance specification

This the constructor for a BirdId object.

#================================================================
# Specification functions
#----------------------------------------------------------------
# normalize(code) ==
#   code, uppercased and right-padded to length ABBR_L
#----------------------------------------------------------------


# - - -   B i r d I d . _ _ i n i t _ _   - - -

    def __init__ ( self, txny, abbr, rel=None, abbr2=None, q=None ):
        """Constructor for BirdId objects"""

        #-- 1 --
        self.txny  =  txny

Next, we store the code or codes in normalized form. If there are two codes, we store the lesser in .abbr and the greater in .abbr2.

        #-- 2 --
        # [ if rel is None or REL_SIMPLE ->
        #     self.abbr  :=  normalize(abbr)
        #     self.rel   :=  None
        #   else ->
        #     self.rel    :=  rel
        #     self.abbr   :=  min(normalize(abbr), normalize(abbr2))
        #     self.abbr2  :=  max(normalize(abbr), normalize(abbr2)) ]
        if  ( ( rel is None ) or ( rel == REL_SIMPLE ) ):
            self.abbr   =  self.normalize ( abbr )
            self.rel    =  None
            self.abbr2  =  None
        else:
            self.rel  =  rel
            abbrList  =  [ self.normalize(abbr),
                           self.normalize(abbr2) ]
            abbrList.sort()
            self.abbr, self.abbr2  =  abbrList

If the q argument is false (None or the empty string), we set self.q to the empty string; otherwise we save its value in self.q.

        #-- 3 --
        # [ if q is false ->
        #     self.q  =  ""
        #   else ->
        #     self.q  =  q ]
        self.q  =  q or ""

Next we build up the .fullAbbr attribute:

        #-- 4 --
        if  self.rel is None:
            self.fullAbbr  =  "%s%s" % (self.abbr, self.q)
        else:
            self.fullAbbr  =  ( "%s%s%s%s" %
                (self.abbr.rstrip(), self.rel,
                 self.abbr2.rstrip(), self.q) )

Lastly, we set up the .taxon attribute by finding the nearest common ancestor of the two forms. In the process, we will also need to look up the taxa for one or both codes. If there is only one code, use its taxon.

        #-- 5 --
        # [ if self.rel is None ->
        #     self.taxon  :=  self.txny's Taxon for self.abbr
        #   else ->
        #     self.taxon  :=  nearest common ancestor of self.abbr
        #         and self.abbr2 in self.txny ]
        if  self.rel is None:
            self.taxon  =  self.txny.lookupAbbr ( self.abbr )
        else:
            taxon1      =  self.txny.lookupAbbr ( self.abbr )
            taxon2      =  self.txny.lookupAbbr ( self.abbr2 )
            self.taxon  =  taxon1.nearestAncestor ( taxon2 )