Bird taxonomy system: internal maintenance specification

Users don't call this constructor directly. Its purpose is to convert XML nodes into Taxon objects. Consequently, its calling sequence looks like this:

# - - -   T a x o n . _ _ i n i t _ _   - - -

    def __init__ ( self, txny, parentTaxon, taxonNode ):
        """Constructor for a Taxon object.
        """

Note that this constructor is recursive. It converts not only the given taxonNode but all its descendants. Pass it the root TAXON_N node, and it will build the entire tree.

The first step is to set up the parts of the object that point elsewhere:

        #-- 1 --
        self.txny         =  txny
        self.parent       =  parentTaxon
        self.__childList  =  []

Next, we set up the parts of the object that are derived from the XML node we're converting:

        #-- 2 --
        # [ self.abbr    :=  STD_ABBR_A attribute from taxonNode, or None
        #                    if there is no such attribute
        #   self.eng     :=  ENG_A attribute from taxonNode
        #   self.rank    :=  rank whose code is the RANK_A
        #                    attribute from taxonNode
        #   self.sci     :=  SCI_A attribute from taxonNode
        #   self.status  :=  STATUS_A attribute from taxonNode, or None
        #                    if there is no such attribute
        #   self.tex     :=  TEX_A attribute from taxonNode, or None if
        #                    there is no such attribute
        #   self.txKey   :=  TX_KEY_A attribute from taxonNode ]
        self.abbr    =  taxonNode.attrib.get(rnc.STD_ABBR_A, None)
        self.eng     =  getChildContent ( taxonNode, rnc.ENG_N )
        wordList     =  self.eng.split()
        rankCode     =  taxonNode.attrib[rnc.RANK_A]
        self.rank    =  txny.hier.lookupRankCode ( rankCode )
        self.sci     =  taxonNode.attrib[rnc.SCI_A]
        self.status  =  taxonNode.attrib.get(rnc.STATUS_A, None)
        self.tex     =  getChildContent ( taxonNode, rnc.TEX_NAME_N )
        self.txKey   =  taxonNode.attrib[rnc.TX_KEY_A]
        if  ( (len(wordList) == 1) or
              (self.rank.depth < txny.hier.speciesRank().depth) ):
            self.engComma = self.eng
        else:
            self.engComma = ( "%s, %s" %
                              (wordList[-1], " ".join(wordList[:-1])) )

Finally, we recursively translate all this node's descendants.

        #-- 3 --
        # [ self.__childList  +:=  Taxon objects made from taxonNode's
        #       children, recursively containing all descendants of
        #       those children ]
        for  childElement in taxonNode.xpath ( rnc.TAXON_N ):
            #-- 3 body --
            # [ self.childList  +:=  a Taxon object made from
            #       childElement, recursively containing all descendants
            #       of childElement ]
            self.__childList.append ( Taxon ( self.txny, self, childElement ) )