Bird taxonomy system: internal maintenance specification

The Hier object is a container for the set of taxonomic ranks used in the classification. Its constructor is not designed to be called directly; that constructor is used only in the initialization of the Txny object.

# - - - - -   c l a s s   H i e r   - - - - -

class Hier:
    """Represents the set of ranks used in the classification.

      Exports:
        Hier ( rankSetNode ):
          [ rankSetNode is a RANK_SET_N Element ->
              return a new Hier object made from rankSetNode ]
        .txKeyLen:
          [ number of characters in a taxonomic key with this
            hierarchy ]
        .canParentHaveChild ( p, c ):
          [ p and c are Rank objects ->
              if there exists a non-optional rank m in self.__rankList
              such that p.depth < m.depth < c.depth ->
                return 0
              else -> return 1 ]
        .genusRank():
          [ if self has a genus rank ->
              return that rank as a Rank object
            else -> return None ]
        .subgenusRank():
          [ if self has a subgenus rank ->
              return that rank as a Rank object
            else -> return None ]
        .speciesRank():
          [ if self has a species rank ->
              return that rank as a Rank object
            else -> return None ]
        .formRank():
          [ if self has a form rank ->
              return that rank as a Rank object
            else -> return None ]
        .lookupRankCode ( rankCode ):
          [ rankCode is a string ->
              if there is a rank in self whose .code equals rankCode ->
                return the corresponding Rank object
              else -> raise KeyError ]
        .__getitem__ ( self, n ):
          [ n is an integer ->
              if n is the rank depth of a rank in self ->
                return that rank
              else -> raise IndexError ]
        .__iter__ ( self ):
          [ return an iterator that yields the ranks in self
            from highest to deepest ]
        .__len__ ( self ):
          [ return the number of ranks in self ]

      State/Invariants:
        .__rankList:
          [ a list of the Rank objects in self from highest to deepest ]
        .__rankCodeMap:
          [ a dictionary whose values are the Rank objects in self,
            and for each value the key is its .code attribute ]
        .__currentRankIndex:
          [ index in self.__rankList when self is an iterator ]
    """

# - - -   H i e r . _ _ i n i t _ _   - - -

    def __init__ ( self, rankSetNode ):
        """Constructor for the Hier object.

          [ rankSetNode is a RANK_SET_N Element ->
              return a new Hier object made from rankSetNode ]
        """

        #-- 1 --
        self.__rankList          =  []
        self.__currentRankIndex  =  0

        #-- 2 --
        # [ self.__rankList  +:=  Rank objects made from the
        #       RANK_N children of rankSetNode, in the same order ]
        for  rankNode in rankSetNode.xpath ( rnc.RANK_N ):
            #-- 2 body --
            # [ rankNode is a RANK_N node ->
            #     self.__rankList  +:=  a Rank object made from rankNode ]
            self.__rankList.append ( Rank ( self, rankNode ) )

        #-- 3 --
        # [ self.txKeyLen  :=  sum of all child rank .keyLen attributes
        #   self.__rankCodeMap  :=  entries mapping R.code |-> R for
        #       R the set of all ranks in self ]
        self.txKeyLen       =  0
        self.__rankCodeMap  =  {}
        for  rank in self.__rankList:
            self.txKeyLen  +=  rank.keyLen
            self.__rankCodeMap[rank.code]  =  rank