nomcompile3: Build a set of nomenclature files

An instance of this class describes a set of taxonomic ranks (such as family, genus, species), and also the ordering of those ranks from the root level (class Aves for bird work) to the deeper ranks. The instance is basically a container object for Rank instances; see Section 16, “class Rank: One taxonomic rank”. Here is the interface.

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

class Hier(object):
    '''Represents an ordered set of taxonomic ranks, higher to lower.

      Exports:
        Hier ( ranksFileName ):
          [ ranksFileName is a string ->
              if ranksFileName names a readable, valid ranks file ->
                return a new Hier instance representing that file
              else ->
                Log()  +:=  error message(s)
                raise IOError ]
        .txKeyLen:
          [ length of a taxonomic key string ]
        .__len__(self):  [ return the number of ranks in self ]
        .__getitem__(self, k):
          [ k is a nonnegative integer ->
             if k < number of ranks in self ->
               return the (k)th rank in self
             else -> raise IndexError ]
        .__iter__(self):
          [ return an iterator that generates the ranks in self
            as a sequence of Rank instances from highest to
            lowest ]
        .__contains__(self, c ):
          [ c is a string ->
              if c is a rank code in self -> return True
              else -> return False ]
        .lookupRankCode ( c ):
          [ c is a string ->
              if c is a rank code in self ->
                return the corresponding Rank instance
              else -> raise KeyError ]
        .canParentHaveChild ( p, c ):
          [ p and c are Rank objects ->
              if (p is higher than c) and
              (there are no required ranks between p and c) ->
                return True
              else -> return False ]
        .keyLen ( depth ):
          [ if depth is the depth of a rank in self ->
              return the key length for that rank
            else -> raise IndexError ]
        .txKeyFill ( shortKey ):
          [ shortKey is a string ->
              return shortKey, right-padded with zeroes to
              size self.txKeyLen ]
        .writeXML ( parent ):
          [ parent is an et.Element ->
              root  :=  root with an rnc.RANK_SET_N element added
                        representing self ]

Internal to the class are these attributes: a sequence of the contained Rank instances, and a dictionary for looking them up by rank code.

      State/Invariants
        .__rankList:
          [ list of contained Rank instances, ordered from highest
            to lowest ]
        .__rankMap:
          [ a dictionary whose keys are the rank codes in self,
            and each corresponding value is a Rank instance,
            and contains keys GENUS_CODE and SPECIES_CODE ]
    '''