xnomo3.py: Internal maintenance specification

This the constructor for a BirdId instance.

#================================================================
# Specification functions
#----------------------------------------------------------------
# standardize(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 instances
        '''

We copy the txny to the instance and also standardize the relationship code using the machinery described in Section 11.2.4, “Relationship codes”.

        #-- 1 --
        self.txny = txny
        self.rel = STANDARD_REL[rel]

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

        #-- 2 --
        # [ if self.rel == REL_SIMPLE ->
        #     self.abbr  :=  standardize(abbr)
        #   else ->
        #     self.abbr   :=  min(standardize(abbr), standardize(abbr2))
        #     self.abbr2  :=  max(standardize(abbr), standardize(abbr2)) ]
        if self.rel == REL_SIMPLE:
            self.abbr = self.standardize ( abbr )
            self.abbr2 = None
        else:
            abbrList = [ self.standardize(abbr),
                           self.standardize(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 == REL_SIMPLE:
            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 == REL_SIMPLE ->
        #     if self.abbr is defined in self.txny ->
        #       self.taxon  :=  self.txny's Taxon for self.abbr
        #     else -> raise KeyError
        #   else ->
        #     if self.abbr and self.abbr2 are both defined in
        #     self.txny ->
        #       self.taxon  :=  nearest common ancestor of self.abbr
        #           and self.abbr2 in self.txny
        #     else -> raise KeyError ]
        if  self.rel == REL_SIMPLE:
            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 )

We also set our .txKey to the value from self.taxon as a pass-through to avoid violating the Law of Demeter.

        #-- 6
        self.txKey = self.taxon.txKey