Assorted machinery having to do with just the bird code
system is relegated to a separate module,
The module contains an assortment of manifest constants and functions, and one class. The constants and functions are:
Maximum length of a bird code, 6 in the CBC system.
A string containing
A regular expression (using Python's standard
re regular expression
module) that describes a valid bird code.
The relationship code for simple (non-compound) forms, one space.
The single-character relationship code denoting
The single-character relationship code denoting a
Abbreviates an English name according to the rules of
the system. Takes a string containing a name either
in the usual word order (e.g.,
Thrush") or in “last,
first” order (e.g.,
Given an English name in the customary order, such as “American Robin”, returns it in the inverted form, e.g., “Robin, American”.
Given an English name in the inverted form, such as “Robin, American”, returns the customary form, e.g., “American Robin”.
Representation of Christmas Bird Count data is complicated considerably by the use of what we call compound forms: species pairs (e.g., “Hammond's/Dusky Flycatcher”) and hybrids (e.g., “Baltimore Oriole×Bullock's Oriole”). Also supported is a trailing “?” to indicate that the identification is only a guess.
Here is the interface to the
which represents simple and compound forms and an optional
BirdId ( txny, abbr, rel=None, abbr2=None, q=None )
connect bird codes to a firm taxonomic foundation,
you must pass a
object as the first argument to the constructor.
The second argument is a bird code. It can be in
either upper or lower case, and either
variable-length or right-padded with spaces. It
will be stored in normalized form: uppercased and
right-padded with spaces to length
For single bird identities, omit the remaining
arguments. For hybrids, pass
rel=REL_HYBRID and the second bird
code in the
q argument should be the string
"?" if the ID is questionable. The
default value is
None, meaning that
the ID is not in question.
Here's an example. Suppose
txny is your
Txny object. This code snippet sets
b1 to a
BirdId object representing Ou (a
Hawaiian endemic), and
representing Indigo × Lazuli Bunting:
b1 = BirdId ( txny, "ou" ) b2 = BirdId ( txny, "lazbun", REL_HYBRID, "indbun" )
This constructor will raise a
KeyError exception if any of the abbreviations are
.txny attribute of a
BirdId object is the
Txny object passed to the
The first or only bird code, normalized. A
normalized code is uppercased, and right-padded
with spaces if necessary to length
For single forms, this attribute is
None. It is set to
REL_HYBRID for hybrids,
REL_PAIR for species pairs.
For compound forms, this attribute holds the second bird code, normalized.
We stipulate that for any
B.abbr2. This means that if you're
looking for a specific hybrid or pair, you don't
have to look in two different places. So we swap
.abbr2 values if necessary to make
this true. For example, in the object returned by
b2 = BirdId ( txny, "lazbun",
REL_HYBRID, "indbun" )”
b2.abbr would be
"lazbun" would be stored in
Has the value
"" (the empty string)
if the ID is not in question;
there is a question about the ID; or
"-" if the ID is correct but the form is
not countable under American Birding Association
This attribute will contain a
Taxon object representing the
smallest taxon that contains this identity. For a
single form, this will be taxonomic key of the
taxon containing the form. For hybrids and species
pairs, it will be taken from the smallest taxon
that is an ancestor of both forms.
Contains a string made from self's
.abbr attribute, with the
.abbr2 attributes concatenated only
for compound forms. Short codes are blank-stripped.
Returns the English name of
inverted order, that is, “last,
"mallard x teal,
This method is called when a
BirdId object is converted to a
string, implicitly or by explicit use of the
str() function. It
returns the English name as a string. Examples of
its return values:
"Blue-winged Teal x
Flycatcher / Hammond's Flycatcher".
BirdId.scan ( txny, scan )
This method works with the
Scan object, from the author's
personal Python library, to process raw bird codes
while scanning an input file. For more information
Scan object, see
the author's library
This is a static method, a relatively new feature of Python. For more information on Python static methods, see the Python 2.2 quick reference.
txny argument is a
Txny object providing the
taxonomy system in which the codes are to be
argument is a
used to scan the input stream containing the bird codes.
This method looks for a bird code, optionally
followed by a relationship code and a second bird
code (which we call a compound
"vireo", for “vireo
mallar^amewig, Mallard × American Wigeon; and
"dowwoo|haiwoo", Downy or Hairy
scan object points
at a valid simple or compound code, the
scan object is advanced past that
code, and the method returns a new
BirdId object representing the code.
scan object doesn't
start with a valid code, an error message is sent
scan object's error
log, and a
exception is raised.
This method will recognize a trailing
"?" if present.
The method raises
KeyError if any
bird codes are undefined.
BirdId.scanFlat ( txny, scan )
This is another static method like
BirdId.scan(), but it expects to see
its input in flat file format. Specifically, the
scan object should start
with three fixed fields. The first field has
ABBR_L and contains
the first or only bird code, left-aligned and
right-padded with spaces. The second field is a
single character and contains the relationship
code: normally blank, but it may contain
REL_PAIR for compound codes. The
third field has length
ABBR_L and contains the second bird
code when the relationship code is nonblank. The
third field must be blank when the relationship
code is blank.
This method does not support the questionable ID
flag. If any codes are undefined, it raises
BirdId.parse ( txny, s )
This static method is also like
BirdId.scan(), but is used when the input
is in an ordinary string instead of a
This method supports a trailing
for questionable IDs. It will raise
KeyError for undefined codes.