Bird taxonomy system: internal maintenance specification

Each taxon in the tree is represented by one Taxon object.

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

class Taxon:
    """Represents one taxonomic grouping of organisms.

      Exports:
        Taxon ( txny, parentTaxon, taxonNode ):
          [ (txny is the containing Txny object) and
            (parentTaxon is the parent Taxon object, or None for root) and
            (taxonNode is a TAXON_N Element) ->
              return a new Taxon object pointing back to txny, with
              parent=parentTaxon, representing taxonNode and its
              descendants ]
        .txny:           [ as passed to constructor, read-only ]
        .parent:         [ parentTaxon passed to constructor, read-only ]
        .abbr:
          [ if self has a standard abbreviation ->
              that abbrevation
            else -> None ]
        .eng:            [ self's English name ]
        .rank:           [ self's taxonomic rank as a Rank object ]
        .sci:            [ self's scientific name ]
        .tex:            [ self's scientific name in TeX format ]
        .txKey:
          [ self's taxonomic key, a string of digits that orders
            taxa in phylogenetic order ]
        .contains ( other ):
          [ other is a Taxon object in self.txny ->
              if self is an ancestor of other ->
                return 1
              else -> return 0 ]
        .nearestAncestor ( other ):
          [ other is a Taxon ->
              return the Taxon representing the nearest ancestor
              of self and other ]
        .__cmp__ ( self, other ):
          [ other is a Taxon ->
              if self precedes other ->
                return a negative number
              else if self is the same as other ->
                return 0
              else -> return a positive number ]
        .__getitem__ ( n ):
          [ n is an integer ->
              if 0 <= n < (number of self's children) ->
                return self's nth child, counting from 0
              else -> raise KeyError ]
        .__iter__ ( self ):
          [ return an iterator that generates self's children
            in taxonomic order ]
        .__len__ ( self ):
          [ return number of self's child taxa ]
        .__str__ ( self ):
          [ return a string representation of self ]

The internal state includes a list of self's child taxa, if any.

      State/Invariant:
        .__childList:
          [ a list of the direct child taxa of self, in phylogenetic
            order, if any, as Taxon objects ]
    """

The private .__childList attribute will hold pointers to self's children, if any.

# - - -   T a x o n . c o n t a i n s   - - -

    def contains ( self, other ):
        """Does self contain other?
        """

        #-- 1 --
        # [ ancestor  :=  nearest ancestor of self and other ]
        ancestor  =  self.nearestAncestor()

        #-- 2 --
        if  self is ancestor:   return 1
        else:                   return 0