IBP banding data system: Internal maintenance specification

The purpose of this abstract class is to provide an interface for looking up species codes. Concrete classes provide this same interface, hiding the details of the structure of the authority file.

Here is the start of the class, and its interface definition.

# - - - - -   c l a s s   B a s e S p e c i e s S e t   - - - - -

class BaseSpeciesSet:
    '''Base class for species code authority files.

      Exports:
        BaseSpeciesSet(fileName):
          [ fileName is a string ->
              if fileName names a readable, valid species code
              authority file ->
                return a new BaseSpeciesSet object representing
                that file
              else -> raise IOError ]
        .lookupSpec4(code):
          [ code is a string ->
              if code matches a 4-letter species code in self,
              case-insensitive ->
                return the Species object with that code
              else -> raise KeyError ]
        .lookupSpec6(code):
          [ code is a string ->
              if code matches a 6-letter species code in self,
              case-insensitive ->
                return the Species object with that code
              else -> raise KeyError ]
        .engRe(re):
          [ re is a compiled Python regular expression ->
              generate the species in self whose English names
              match re ]

Here are the internal structures for instances of this class: three dictionaries for looking up species by four- and six-letter codes, or by English name.

      State/Invariants:
        .spec4Map:
          [ a dictionary whose keys are the uppercased 4-letter
            codes in self, and each corresponding value is the
            Species object that has that code ]
        .spec6Map:
          [ a dictionary whose keys are the uppercased 6-letter
            codes in self, and each corresponding value is the
            Species object that has that code ]
        .engMap:
          [ a dictionary whose keys are the English names in
            self, and each corresponding value is the Species
            object that has that name ]
    '''

Note that the English names in .engMap are in mixed-case.

# - - -   B a s e S p e c i e s S e t . l o o k u p S p e c 4   - - -

    def lookupSpec4(self, code):
        '''Look up a 4-letter code.
        '''
        return self.spec4Map [ code.upper() ]