9. The Python taxonomy package, txny.py: the interface

9. The Python taxonomy package, `txny.py`: the interface

The author considers the Python language the best general-purpose programming currently available. This section describes a Python-language module suited for putting a firm taxonomic foundation under bird records work.

Python module txny.py provides access to an XML taxonomy file as described above under Section 8, “Schema for the XML product file”. It insulates you from the XML files, providing attributes and methods that allow you to look up bird codes and other common operations in bird records management.

To use this module, import it like this:

from txny import *

Here are the exported classes available in the txny.py module.

9.1. Class `Txny`: the complete system

Normally the first thing you'll do is instantiate a Txny object, which represents the entire system—taxonomy and bird codes:

Txny ( dataFile=None )

Reads the XML data file and returns a Txny object representing that file.

If no argument is supplied, this constructor looks for a file named aou.xml in the current directory.

If there is no readable, valid XML file, the constructor raises an IOError exception.

Attributes of a Txny object include:

.root: The root taxon of the taxonomic arrangement, as a Taxon object. See Section 9.4, “The Taxon class: One node in the classification tree”.
.hier: Contains a Hier object representing the set of taxonomic ranks used. See Section 9.2, “Class Hier: The set of taxonomic ranks”.

Methods on a Txny object include:

.lookupTxKey(txKey)

Looks for the taxon corresponding to taxonomic key number txKey and returns it as a Taxon object. Raises a KeyError exception if the arrangement has no such key.

.lookupSci(sci)

Looks for the taxon whose scientific name matches sci, and returns it as a Taxon object. This is a case-sensitive comparison. If there is no taxon in this arrangement with the given scientific name, raises KeyError.

.lookupAbbr(abbr)

Looks for the taxon that is equivalent to bird code abbr, and returns it as a Taxon object.

.lookupCollision(abbr)

If abbr is one of the bird codes disallowed because it is a collision, this method returns a list of the valid substitute codes. For example, this call

    txny.lookupCollision("BAROWL")

would return the list ["BRDOWL", "BRNOWL"].

Raises KeyError if abbr is not a collision code.

.genTxKeys()

Generates the taxonomic keys in the arrangement in ascending (phylogenetic) order, as strings. In case you are not familiar with Python generators, a relatively new language feature, see Python 2.2 quick reference under the section “Recent features.”

.genAbbrs()

Generates the valid bird codes in self, in ascending order, uppercased.

.abbrToEng(abbr)

Returns the English name from which the given abbreviation abbr was derived. Raises KeyError if abbr is not valid.

.abbrToTeX(abbr)

Returns the English name from which the given abbreviation abbr was derived, marked up for TeX. If there is no specific TeX markup, it returns the English name as regular text. Raises KeyError if abbr is not valid.

Here's a brief example. Assume you have a taxonomy file named aou.xml in your directory, and you want to print out the scientific name and English name corresponding to the code 'GOCKIN'. This code would do the trick:

from txny import *

txny = Txny ( 'aou.xml' )
taxon = txny.lookupAbbr ( 'gockin' )
print "%s [%s]" % (taxon.eng, taxon.sci)

This will print the line:

Golden-crowned Kinglet [Regulus calendula]

A system for representing bird taxonomy