Bird taxonomy system: internal maintenance specification

Here is the class constructor, which takes as its argument the name of the XML data file.

# - - -   T x n y . _ _ i n i t _ _   - - -

    def __init__ ( self, dataFile=None ):
        """Constructor for the Txny object.
        """

First we figure out the actual file name we're reading:

        #-- 1 --
        if  dataFile is None:
            fileName  =  DEFAULT_FILE_NAME
        else:
            fileName  =  dataFile

The next step is to read the entire XML file. This will succeed if the file is readable and well-formed, but it will raise an exception otherwise.

        #-- 2 --
        # [ if fileName names a readable, well-formed XML file ->
        #     doc   :=  a Document node representing that file
        #     root  :=  an Element node representing the file's
        #               root element
        #   else -> raise IOError ]
        try:
            doc  =  et.parse ( fileName )
            root  =  doc.getroot()
        except Exception, detail:
            raise IOError, ( "Error reading the taxonomy file "
                "'%s': %s" %
                (fileName, detail) )

First we process the rankSet element, which returns a Hier object:

        #-- 3 --
        # [ self.hier  :=  a new Hier object made from root's
        #                  RANK_SET_N subtree ]
        rankSetNode  =  root.xpath ( rnc.RANK_SET_N )[0]
        self.hier  =  Hier ( rankSetNode )

Next we process the taxonomic tree:

        #-- 4 --
        # [ self.root  :=  a Taxon object made from root's TAXONOMY_N
        #       subtree, with children representing that subtree
        #   self.__txKeyMap  :=  as invariant, from that subtree
        #   self.__sciMap    :=  as invariant, from that subtree ]
        taxonomyNode  =  root.xpath ( rnc.TAXONOMY_N )[0]
        self.__readTaxonomy ( taxonomyNode )

Now, read the set of valid bird codes, then the set of collisions:

        #-- 5 --
        # [ self.__abbrMap  :=  as invariant, from root's ABBR_SET_N
        #                       subtree
        #   self.__abbrEng  :=  as invariant, from that subtree
        #   self.__abbrTex  :=  as invariant, from that subtree ]
        abbrSetNode  =  root.xpath ( rnc.ABBR_SET_N )[0]
        self.__readAbbrs ( abbrSetNode )

        #-- 6 --
        # [ self.__collMap  :=  as invariant, from root's
        #                       COLLISION_SET_N subtree ]
        collSetNode  =  root.xpath ( rnc.COLLISION_SET_N )[0]
        self.__readCollisions ( collSetNode )