5. birdimages.py: A Python object for the catalog

5. `birdimages.py`: A Python object for the catalog

The birdimages.py module is a Python module containing a class that represents the contents of a slide catalog.

This section describes the external interface to the module. For the actual code of the module, see Section 6, “birdimages.py: Internals”.

5.1. The `ImageCatalog` object

To access the image catalog:

from birdimages.py import *

C = ImageCatalog.readFile(filename)

where filename is the name of the image catalog. If omitted, this file name defaults to “birdimages.xml” in the current directory. If the file does not exist or is not well-formed, this method will raise IOError.

The code above would set cat to an instance of the ImageCatalogclass. An ImageCatalog instance C exports these methods:

C.getOriginal(catNo)

If the catalog contains an original image whose catalog number matches catNo, the method returns an Original instance that represents the catalog entry. See Section 5.2, “class Original: One bird slide catalog entry”.

If the catalog contains no image with that number, the method raises a KeyError exception.

C.genOriginals()

Using a Python generator, this method generates all the entries in C as instances of class Original, in ascending order by catalog number.

C.genAb6(birdId)

This method generates, as a sorted sequence of Original instances, all the catalog entries that contain a given kind of bird. The argument birdId is a string whose syntax is described in A system for representing bird taxonomy, in the section on the abbr.py module.

Typically the argument is a six-letter bird code (e.g., "BALEAG" for Bald Eagle), but it may also be a string representing a species pair (e.g., "DOWWOO|HAIWOO" for Downy or Hairy Woodpecker) or a hybrid (e.g., "AMEWIG^EURWIG for American × European Wigeon).

A question mark may be appended to any of the above values, e.g., “HAMFLY?” or “AMEWIG^EURWIG?”. If a form appears both with and without the question mark, that is considered two different forms.

5.2. `class Original`: One bird slide catalog entry

An instance of this class represents one catalog entry. The related schema pattern is described in Section 3.3, “original: Data for one exposure”.

An instance O of class Original exports these read-only attributes:

O.catNo: The catalog number.
O.ab6: The full ab6 attribute, containing one or more bird ID strings.
O.state: State code.
O.qual: The qual attribute, if any, otherwise an empty string.
O.scan: The scan attribute as an integer, if present; otherwise None.
O.loc: The contents of the loc element, or an empty string if that element is missing.
O.note: The contents of the note element, or an empty string.
O.film: The text from the film element if present, or an empty string.
O.light: The light description from the light element, or an empty string.
O.beh: Behavior notes from the beh element, or an empty string.
O.desc: Description from the desc element, or an empty string.
O.pose: Posing information from the pose element, or an empty string.

An XML-based bird image cataloging system