xnomo3.py: Internal maintenance specification

We start off with class Txny. Here is its external interface:

# - - - - -   c l a s s   T x n y   - - - - -

class Txny:
    """Object to represent the entire taxonomy and code system.

      Exports:
        Txny ( dataFile=None ):
          [ dataFile is a string, defaulting to DEFAULT_FILE_NAME ->
              if dataFile names a readable XML file that
              validates against txny.rnc ->
                return a new Txny instance representing that file
              else -> raise IOError ]
        .genAbbrs():
          [ generate all valid bird codes in self, in ascending
            order ]
        .genTxKeys():
          [ generate all the taxonomy keys in self, in ascending
            order ]
        .lookupAbbr ( abbr ):
          [ abbr is a string ->
              if self contains a Taxon whose .abbr attribute
              matches abbr, case-insensitive and blank-padded ->
                return that Taxon
              else -> raise KeyError ]
        .lookupCollision ( abbr ):
          [ abbr is a string ->
              if self contains a collision code matching abbr,
              case-insensitive ->
                return a list of the valid alternative codes
              else -> raise KeyError ]
        .lookupSci ( sci ):
          [ sci is a string ->
              if self contains a taxon whose scientific name matches
              sci ->
                return that taxon as a Taxon instance
              else -> raise KeyError ]
        .lookupTxKey ( txKey ):
          [ txKey is a string ->
              if self contains a Taxon whose .txKey attribute
              matches txKey ->
                return that Taxon
              else -> raise KeyError ]
        .abbrToEng ( abbr ):
          [ abbr is a string ->
              if abbr is a bird code in self ->
                return the corresponding English name
              else -> raise KeyError ]
        .abbrToHtml ( abbr, cssClass=None ):
          [ (abbr is a string) and
            (cssClass is a string or None) ->
              if abbr is a bird code in self ->
                if cssClass is None ->
                  return the corresponding English name marked up for
                  HTML with the deprecated 'i' element
                else ->
                  return the corresponding English name marked up for
                  HTML with a span element whose class is (cssClass)
              else -> raise KeyError ]
        .abbrToTeX ( abbr ):
          [ abbr is a string ->
              if abbr is a bird code in self ->
                return the corresponding TeX name
              else -> raise KeyError ]

The various lookup functions require that we have internal dictionaries to map the various names, keys and codes to Taxon instances.

      State/Invariants:
        .__abbrMap:
          [ a dictionary whose keys are the bird codes in self, 
            uppercased and blank-filled, and each related value is
            the corresponding Taxon instance ]
        .__collMap:
          [ a dictionary whose keys are the collision codes in self,
            uppercased and blank-filled, and their corresponding
            values are lists of the valid substite codes ]
        .__sciMap:
          [ a dictionary whose keys are the .sci attributes of the
            the Taxon instances in self, and each related value is
            the corresponding Taxon instance ]
        .__txKeyMap:
          [ a dictionary whose keys are the .txKey attributes of the
            Taxon instances in self, and each related value is that
            Taxon instance ]
        .__abbrEng:
          [ a dictionary whose keys are the bird codes in self,
            uppercased and blank-filled, and each related value
            is the English name from which that code was derived,
            using "_" to mark up italicized parts ]
    """

# - - -   T x n y . g e n A b b r s   - - -

    def genAbbrs ( self ):
        """Generate all valid bird codes in self.
        """
        keyList = self.__abbrMap.keys()
        keyList.sort()
        for  key in keyList:
            yield key