xnomo3.py: Internal maintenance specification

Abstract

Describes the implementation of a system for representing a classification of a set of birds, using the Python programming language and XML (Extensible Markup Language).

This publication is available in Web form and also as a PDF document. Please forward any comments to john@nmt.edu.

Table of Contents

1. Introduction

2. Definitions

3. The xnomo3.py module: prologue

4. Imported modules

5. Manifest constants

5.1. DEFAULT_FILE_NAME
5.2. ABBR_L
5.3. GENUS_RANK_CODE
5.4. SUBGENUS_RANK_CODE
5.5. SPECIES_RANK_CODE
5.6. FORM_RANK_CODE
5.7. LDQUO
5.8. RDQUO
5.9. UNI_LQ
5.10. UNI_RQ
5.11. TEX_LQ
5.12. TEX_RQ
5.13. TEX_ITAL_START
5.14. TEX_ITAL_END

6. class Txny

6.1. Txny.genAbbrs(): Generate all valid bird codes
6.2. Txny.genTxKeys(): Generate all phylogenetic key numbers
6.3. Txny.lookupAbbr()
6.4. Txny.lookupCollision()
6.5. Txny.lookupSci()
6.6. Txny.lookupTxKey()
6.7. Txny.abbrToEng()
6.8. Txny.abbrToEngComma()
6.9. Txny.abbrToHtml()
6.10. Txny.abbrToHtmlComma()
6.11. Txny.abbrHtmlSubelt()
6.12. Txny.abbrHtmlSubeltComma()
6.13. Txny.abbrToTeX()
6.14. Txny.abbrToTeXComma()
6.15. Txny.abbrToRawEng()
6.16. Txny.__init__()
6.17. Txny.__openDoc(): Open and validate the XML file
6.18. Txny.__readTaxonomy()
6.19. Txny.__buildMaps(): Index by key and scientific name
6.20. Txny.__addTaxonMaps(): Add a taxon to the internal dictionaries
6.21. Txny.__readAbbrs()
6.22. Txny.__readCollisions()
6.23. Txny.__addCollision(): Add one collision

7. class Hier

7.1. Hier.__init__()
7.2. Hier.canParentHaveChild()
7.3. Hier.formRank(), Hier.genusRank(), Hier.speciesRank(), and Hier.subgenusRank()
7.4. Hier.lookupRankCode()
7.5. Hier.__getItem__()
7.6. Hier.__iter__()
7.7. Hier.__len__()

8. class Rank: One taxonomic rank

8.1. Rank.__init__()
8.2. Rank.__str__()

9. class Taxon

9.1. Taxon.contains()
9.2. Taxon.nearestAncestor()
9.3. Taxon.childContaining(): Find child containing a descendant
9.4. Taxon.__cmp__(): Compare taxa in phylogenetic order
9.5. Taxon.__getitem__()
9.6. Taxon.__iter__()
9.7. Taxon.__len__()
9.8. Taxon.__str__()
9.9. Taxon.engHtml()
9.10. Taxon.engHtmlComma()
9.11. Taxon.engHtmlSubelt()
9.12. Taxon.engHtmlSubeltComma()
9.13. Taxon.__init__(): The constructor
9.14. Taxon.__engNames(): Build the variants on the English name

10. Utility functions for the xnomo3.py module

10.1. htmlify(): Mark up text for HTML
10.2. htmlSubelt(): Add a name to an et.Element
10.3. uniQuotes(): Convert double-quotes to Unicode paired form
10.4. class Htmler: State machine for HTML markup
10.5. Htmler.__init__()
10.6. Htmler.convert()
10.7. Htmler._italStart()
10.8. Htmler._italEnd()
10.9. texify(): Mark up text for T_EX
10.10. class Texer: State machine for T_EX markup
10.11. Texer.__init__()
10.12. Texer.convert()

11. The abbr.py module

11.1. Prologue
11.2. Manifest constants
11.3. abbreviate()
11.4. engComma(): Invert an English name
11.5. engDeComma(): Normalize an English name
11.6. fixAbbr(): Standardize a bird code
11.7. class BirdId
11.8. BirdId.__init__()
11.9. BirdId.standardize()
11.10. birdId.engComma(): Inverted English name
11.11. BirdId.commafy(): Invert word order (static method)
11.12. BirdId.__str__()
11.13. BirdId.scan()
11.14. BirdId.scanFlat()
11.15. BirdId.scanAbbr()
11.16. BirdId.scanAbbrFlat()
11.17. BirdId.parse(): Parse a code from a string

12. test3: A test driver

1. Introduction

This document describes the internals of the programs associated with xnomo3: A system for representing bird taxonomy. Refer to that document for downloadable online files.

In addition to its utility in bird records management, this module is also an example of several useful techniques:

Literate programming, the writing of code and documentation as a single process with a single source file. See the author's page on lightweight literate programming.
For the program that extracts the Python source code from this document's DocBook-XML source file, see litlxml: A source extractor for lightweight literate programming.
Cleanroom (zero-defect) programming. See Toward Zero-defect Programming by Allan M. Stavely (Addison-Wesley, 1999, ISBN 0-201-38595-3) for an overview of this methodology, and see also the author's Cleanroom pages for details of the method as he practices it.
XML processing using the Python lxml package; see Python XML processing with lxml.