Next / Previous / Contents / Shipman's homepage


This document describes the internals of a Python-language module to represent birdwatching field notes in XML.

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

Table of Contents

1. Overview
2. Module prologue
3. Specification functions
3.1. phylo-key
4. Module imports
5. Manifest constants
5.1. SCHEMA_RNG: Schema file name
5.2. YEAR_PAT: Year directory name pattern
5.3. YYYY_MM_XML_PAT: Month file name pattern
6. Generic node readers and writers: .readNode() and .writeNode()
7. class BirdNoteSet: One file's worth of notes
7.1. BirdNoteSet.__init__(): Constructor
7.2. BirdNoteSet.addDay(): Add one day list
7.3. BirdNoteSet.genDays(): Generate days in self
7.4. BirdNoteSet.readFile(): Add a file's content
7.5. BirdNoteSet._fileTime(): Update the most recent modification time
7.6. BirdNoteSet._validate(): Open and validate the file
7.7. BirdNoteSet.writeFile(): Translate to XML
8. class DayNotes: Notes from one date and state
8.1. DayNotes.title(): Daily full title
8.2. DayNotes.defaultLoc(): Return the default location
8.3. DayNotes.addLoc()
8.4. DayNotes.lookupLoc(): Look up a location code
8.5. DayNotes.addForm(): Add a form to one day's notes
8.6. DayNotes.lookupForm()
8.7. DayNotes._phyloKey()
8.8. DayNotes.genForms(): Generate forms in phylogenetic order
8.9. DayNotes.genFormsSeq(): Generate forms in the order they were added
8.10. DayNotes.__init__(): Constructor
8.11. DayNotes.writeNode(): Internal form to XML
8.12. DayNotes.readNode(): XML to internal form
9. class DaySummary: Daily summary
9.1. DaySummary.__init__()
9.2. DaySummary.defaultLoc(): Return the default location
9.3. DaySummary.addLoc(): Add a location definition
9.4. DaySummary.lookupLoc(): Find a location by its code
9.5. DaySummary.genLocs(): Generate all locations
9.6. DaySummary.readNode(): Convert from XML (static method)
9.7. DaySummary.dayAnnotation(): Process day-annotation content
9.8. DaySummary.writeNode(): Translate to XML
10. class Loc: Locality code definition
10.1. Loc.__init__(): Constructor
10.2. Loc.addGps(): Add a waypoint
10.3. Loc.genGps(): Generate waypoints
10.4. Loc.readNode(): Convert from XML (static method)
10.5. Loc.writeNode(): Translate to XML
11. class Gps: GPS waypoint
11.1. Gps.__init__()
11.2. Gps.readNode() (static method)
11.3. Gps.writeNode(): Convert to XML
12. class BirdForm: Notes for one kind of bird
12.1. BirdForm.__len__(): Number of sightings
12.2. BirdForm.__getitem__(): Index function
12.3. BirdForm.addSighting()
12.4. BirdForm.genSightings()
12.5. BirdForm.__init__()
12.6. BirdForm.getLocGroup(): Find the effective locality
12.7. BirdForm.readNode() (static method)
12.8. BirdForm.getTaxonGroup() (static method)
12.9. BirdForm.singleSighting(): Read a single sighting
12.10. BirdForm.multiSighting(): Read the multi-sighting case
12.11. BirdForm.readFloc(): Read one floc element
12.12. BirdForm.writeNode(): Translate to XML
12.13. BirdForm._writeTaxonGroup()
12.14. BirdForm.writeSingle(): Create single-sighting XML
12.15. BirdForm.writeMulti(): Create multi-sighting XML
13. class Sighting: Sighting group
13.1. Sighting.__init__()
13.2. Sighting.getLocGroup(): Find a sighting's effective locality
13.3. Sighting.writeNode(): Translate to XML
14. class LocGroup: Sighting's locality
14.1. LocGroup.__init__()
14.2. LocGroup.readNode(): Extract loc-group content
14.3. LocGroup.inherit(): Implement inheritance for locations
14.4. LocGroup.writeNode(): Translate to XML
15. class AgeSexGroup: Sighting core data
15.1. AgeSexGroup.__init__()
15.2. AgeSexGroup.readNode() (static method)
15.3. AgeSexGroup.writeNode()
16. class SightNotes: Optional notes
16.1. SightNotes.__init__()
16.2. SightNotes.addPhoto()
16.3. SightNotes.genPhotos(): Generate photos
16.4. SightNotes.addPara(): Add a paragraph of notes
16.5. SightNotes.readNode() (static method)
16.6. SightNotes.writeNode()
16.7. SightNotes.writeChild(): Attach narrative to a child
17. class Photo: Photo link
17.1. Photo.__init__()
17.2. Photo.readNode() (static method)
17.3. Photo.writeNode()
18. class Narrative: Narrative elements
18.1. Narrative.__init__(): Constructor
18.2. Narrative.addPara(): Add a paragraph
18.3. Narrative.__len__(): How many paragraphs?
18.4. Narrative.__getitem__(): Get one paragraph
18.5. Narrative.genParas(): Generate self's contained paragraphs
18.6. Narrative.writeNode(): Write as XML
18.7. Narrative.readNode(): Read XML (static method)
18.8. Narrative.readChild() (static method)
19. class Paragraph: One paragraph of mixed text
19.1. Paragraph.__init__(): Constructor
19.2. Paragraph.addContent()
19.3. Paragraph.genContent(): Generate the content
19.4. Paragraph.writeNode(): Write as XML
19.5. Paragraph.writeContent(): Write the content of a paragraph
19.6. Paragraph._writeParaChild()
19.7. Paragraph.readNode(): Process a para element (static method)
19.8. Paragraph.addPhrase(): Add one phrase to the paragraph
20. class BirdNoteTree
20.1. BirdNoteTree.__init__(): Constructor
20.2. BirdNoteTree._findMonths(): Scan yearly directories
20.3. BirdNoteTree.genMonths(): Read monthly files
20.4. BirdNoteTree._timeFilter(): Check date and seasonal ranges
20.5. BirdNoteTree._readMonth()
21. class FlatSighting: Complete sighting record
21.1. FlatSighting.__init__(): Constructor
21.2. FlatSighting.sanitize(): Strip Unicode characters from locality name
21.3. FlatSighting.delimited(): Output a spreadsheet record
22. Testing
22.1. Sample XML input file
22.2. identitest: Round-trip test script
22.3. treetest: Test driver for BirdNoteTree
22.4. flattest: Flatten the entire database

1. Overview

A system for encoding bird field notes describes an XML schema for encoding birdwatching field notes, along with a Python module that reads and writes XML files conforming to that schema. This document contains the actual code for the module, in literate programming style. For more information, see the author's literate programming page.

The module reads and writes XML using techniques described in Python XML processing with lxml. The reader should be familiar with Python and XML.

Files referred to in this document:

The module exports a number of classes. Each represents an XML element. As an entity-relationship diagram:

This diagram does not show the Narrative class, which appears at multiple places, and can have zero or more Paragraph children.