AviListPy

AviListPy is a Python package for quickly accessing data from the AviList Global Check List. AviList is meant to be a single unified data base for bird taxonomy that will be adopted by many different ornithology authorities. Of particular interest to the average birder is that the Cornell Lab of Ornithology, the team behind eBird and Merlin, have stated their plans to conform to this checklist completely by 2026.

AviList Core Team. 2025. AviList: The Global Avian Checklist, v2025. https://doi.org/10.2173/avilist.v2025

AviListPy Design/Features

• Lightweight classes for quickly accessing data from the AviList Checklist
• Data base class built on top of a Pandas DataFrame with convenient methods for data accessibility
  • Once initialized, can be saved and loaded to access the entire data base in a few milliseconds
• Classes for each taxonomic rank with dictionary-like access to data columns in the AviList CheckList

Installation

Currently AviListPy is only available on PyPi and must be installed with pip, but I plan to add support for conda-forge in the near future. Fo

With Pip

pip install AviListPy

With Conda/Mamba

If you plan to use this in a larger environment, you may want to install AviListPy's dependencies and all other packages with conda/mamba, and then install AviList without dependencies using pip.

conda create -n AviListPy python=3.12 pandas openpyxl or mamba create -n AviListPy python=3.12 pandas openpyxl

Or if you want to install into an existing environment: conda install pandas openpyxl or mamba install pandas openpyxl

Then install with pip: pip install AviListPy --no-deps

Troubleshooting

I have inconsistently found that pip will insist on installing version 1.0.0, which incorrectly defined dependencies. If pip fails to install AviListPy, try: pip install AviListPy --no-cache-dir or pip cache purge to clear cached versions, and install normally.

Usage

First Time Use

AviListPy uses the AviListDataBase class as a very light weight wrapper for a Pandas DataFrame containing the actual Excel file from the AviList team. This AviListDataBase is used by every taxonomic class, and an instance of the database can be passed directly to each taxonomic object when initializing, or these classes can create their own directly from the AviList excel file. It is recommended to initialize a single instanec of AviListDatabase at the beginning of your script and pass it to taxonomic classes, because it takes about 10 seconds to load the entire excel sheet. AviListDataBase can also be fed a file path, where it will pickle itself or look for an already pickled version of itself to load in. This is the fastest option, bringing the load time to a few milliseconds as opposed to the several seconds to load the Excel sheet itself.

Example Setup

from AviList.database.avilistdatabase import AviListDataBase

db = AviListDataBase(path='/path/to/database/AviListDataBase.db')

db can then be passed to all taxonomic objects in your script.

Entries in the data base can be accessed by initializing the AviList.taxonomy object matching their given rank. For example, AviList.taxonomy.species.Species:

from AviList.taxonomy.species import Species

species = Species('American Redstart', db=db)

The Species class contains its corresponding row in the AviList data base in a dictionary-like manner. For example, the AviList column English_name_AviList can be accessed by:

species['English_name_AviList']

These classes have a few of these values written directly as attributes as well for ease of use, such as species.Family. These values can still be accessed in the same dictionary like manner. species.name contains a species plain English name, species.scientific_name contains its scientific name. Currently, all other taxonomic ranks have the scientific name saved to the .name attribute.

By default, subspecies are not loaded. This can be changed by setting load_subspecies=True while intitializing the Species class. These are saved to the Species.subspecies attribute as a list of AviList.taxonomy.subspecies.Subspecies objects. When print() is called on any taxonomic object in AviListPy, it gives a line or two of basic information, then just writes column: value for the given row in the AviListDataBase.

For higher taxonomic ranks, lower taxonomic ranks are also loaded in and saved to a list within the higher ranked object. For example:

from AviList.taxomomy.genus import Genus

genus = Genus('Calidris', db=db)

genus.species contains a list of Species objects

Higher ranks also contain methods that given information about the lower ranked taxons that they contain. For example,

from AviList.taxonomy.family import Family

family = Family('Podargidae', db=db)
family.show_genera()

This will give basic information about how many genera this family contains. family.genera is an attribute that contains a list of Genera objects.

Higher taxonomic ranks can also be passed load_subspecies=True, which is just passed to Species objects when they are initialized.