Squirrel Census

Day 25 of Udemy's 100 Days of Code: The Complete Python Pro Bootcamp: count the squirrels of the 2018 Central Park Squirrel Census by primary fur colour (gray, cinnamon, black) and export the counts to squirrel_count.csv. Python 3.13 or later, no runtime dependencies, with tests and source documentation.

Requirements

• Python 3.13 or later (python --version on Windows, python3 --version on Linux and macOS).
• venv, which ships with Python (on Debian: the python3-venv package).
• The 2018 census file. It is already in the repository under data/.
• Optional: Doxygen 1.9 or later, only to build the source documentation.

There are no runtime dependencies: the program uses only the Python standard library (ADR-0001). pytest is needed only to run the tests.

Set up

Create a local virtual environment named .venv in the project folder, upgrade pip and install the project with its development tools (pytest, ruff, mypy, yamllint, actionlint).

Windows powershell

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

If PowerShell refuses to run the activation script, allow it for the current session: Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned.

Linux debian

sudo apt install python3 python3-venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

MacOS

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

On macOS, Python 3.13 can be installed with brew install python@3.13.

Run

With the virtual environment active, run from the project folder:

python -m squirrel

The program reads data/2018_Central_Park_Squirrel_Census_-_Squirrel_Data.csv, prints the colour counts and writes squirrel_count.csv:

Gray: 2473
Cinnamon: 392
Black: 103

Use other files by passing them as arguments, python -m squirrel <census file> <summary file>. If the census file does not exist the program prints a message and exits with status 2.

Run the tests

python -m pytest

The tests use small fixture rows; one test also checks the real 2018 census file when it is present.

Continuous integration

The workflow .gitea/workflows/ci.yml runs for every push to main and for every pull request. It sets up Python 3.13, creates a .venv, upgrades pip, installs the project with .[dev], lints the YAML and workflow files with yamllint and actionlint, and runs python -m pytest. It uses github.* contexts only, so it also runs on GitHub Actions.

Build the source documentation

The source is documented with Doxygen comments and configured by Doxyfile.

doxygen Doxyfile

Open docs/doxygen/html/index.html in a browser. The output folder is ignored by git.

Project layout

.gitea/workflows/ci.yml   continuous integration workflow
data/                     the 2018 census file
docs/                     business case, plan, milestones, models, reviews, ADRs
docs/images/              screenshots used by this README and the wiki
src/squirrel/             the package: census.py, cli.py, constants.py
tests/                    pytest tests
wiki/                     wiki pages in English, Danish (.da) and Bahasa Malaysia (.ms)
Doxyfile                  Doxygen configuration
pyproject.toml            project configuration (Python >=3.13, no runtime dependencies)
squirrel_count.csv        the result of the assignment

The project documents, in reading order: Business Case, Stakeholder Analysis, Project Plan, Use Case, Domain Model, ADR-0001. The repository also has a wiki in English, Danish and Bahasa Malaysia.

License

GNU Affero General Public License v3.0 or later. See LICENSE.

---