Robot Python Projects

The following directories contain the robot Python projects — packages that run on or support Opentrons robots:

Common Patterns

• Build system: pyproject.toml with hatchling (hatchling==1.27.0)
• Dependency management: uv with uv.lock files (not pipenv or poetry)
• Python version: 3.12 (set via UV_PYTHON = 3.12 in scripts/python-uv.mk)
• Testing: pytest 9+ with config in [tool.pytest] section of pyproject.toml
• Linting: ruff (replaces flake8 + isort) with config in [tool.ruff] sections of pyproject.toml
• Type checking: mypy with config in [tool.mypy] section of pyproject.toml (not mypy.ini)
• Shared Make includes: all Makefiles include ../scripts/python-uv.mk which provides common targets

Running Tests

Prefer running tests scoped to the project where your changes are:

# From the project directory
cd api && make test

# Or from the monorepo root
make -C api test

Each project has a Makefile with a test target. The exception is shared-data, which uses test-py:

make -C shared-data test-py

Checking Types and Linting

Each project has a Makefile with a lint target (runs ruff check + mypy). shared-data uses lint-py:

make -C api lint
make -C shared-data lint-py

Formatting

Each project has a Makefile with a format target (runs ruff format + isort fix). shared-data uses format-py:

make -C api format
make -C shared-data format-py

Setup and Teardown

Each project has setup and teardown targets. Setup runs uv sync --frozen --group dev --python 3.12. shared-data uses setup-py and teardown-py:

make -C api setup
make -C shared-data setup-py

Or from the monorepo root for all robot Python projects at once:

make setup-py      # setup all
make teardown-py   # teardown all

Dependency Management

cd api  # or any robot Python project

uv add <package>              # add production dependency
uv add --group dev <package>  # add dev dependency
uv remove <package>           # remove dependency
uv lock                       # re-resolve after manual pyproject.toml edits

After changing dependencies, commit both pyproject.toml and uv.lock.