Install fails on macOS built-in Python 3.9: requires-python allows 3.9 but pinned deps need 3.11+ #324

pyproject.toml declares requires-python = ">=3.9", but several pins in requirements.txt need a newer Python. On macOS, the python3 that ships with Apple's command-line tools is 3.9.6, so a Mac user following the README install steps hits a failure that never mentions the Python version as the cause.

What happens on macOS's built-in Python 3.9.6

Following the README exactly (python3 -m venv .venv, then pip install -r requirements.txt):

1. Apple's Python ships pip 21.2.4, which can't do an editable install of a pyproject-only package, so the -e . line fails first:

   ERROR: File "setup.py" or "setup.cfg" not found. Directory cannot be installed in editable mode
   

2. After pip install --upgrade pip, resolution fails on the first pin that needs a newer Python:

   ERROR: No matching distribution found for click==8.3.0
   

   (click 8.3.0 requires Python >=3.10.)

pandas==3.0.0 requires Python >=3.11, so Python 3.10 fails too (confirmed with a clean 3.10 environment). The effective floor for the pinned requirements is 3.11.

The same install on Python 3.14.6 (macOS, Apple Silicon) works, and the full pytest suite passes.

Suggested fix

• Raise requires-python in pyproject.toml to ">=3.11" so pip stops early with a clear version error.
• Add a short prerequisites note to the README Installation section: Python 3.11+ required. On macOS the built-in python3 is 3.9, so install a newer one via Homebrew (brew install python@3.13), python.org, or uv venv --python 3.13.

Happy to open a PR for this if that's useful.