Contributing#

This page covers the local development workflow for labapi: running tests, enforcing code style, and following the project’s type-system conventions.

Setup#

Install the package with its development dependencies using uv:

uv sync --all-groups
pre-commit install --hook-type pre-commit --hook-type pre-push

Running Tests#

The test suite is split into unit tests and integration tests. Plain pytest deselects integration tests by default.

Run the full suite, including integration tests, with:

uv run pytest --integration

Unit Tests#

Unit tests use a MockClient that replays pre-recorded API responses, so they run entirely offline.

uv run pytest
uv run pytest --no-cov
uv run pytest tests/tree/test_mixins.py

Integration Tests#

Integration tests hit the live LabArchives API and require credentials in the environment or a .env file:

ACCESS_KEYID=your_akid
ACCESS_PWD=your_password
API_URL=https://api.labarchives.com

AUTH_EMAIL=your@email.com
AUTH_KEY=your_auth_key

# Optional: use the browser callback flow instead
# AUTH_INTERACTIVE=true

Run them explicitly with:

uv run pytest --integration tests/test_integration.py

Note

Client only auto-loads API_URL, ACCESS_KEYID, and ACCESS_PWD. AUTH_EMAIL and AUTH_KEY are conventions used by this repository’s integration-test fixtures.

Code Style#

labapi uses Ruff for both linting and formatting.

Pre-commit Hooks#

After running pre-commit install --hook-type pre-commit --hook-type pre-push:

  • ruff-check lints and auto-fixes safe issues.

  • ruff-format enforces consistent formatting.

  • pytest-check runs uv run pytest --no-cov on pre-push.

Run the checks manually with:

uv run ruff check --fix .
uv run ruff format .
uv run pytest --no-cov

Or check without making changes:

uv run ruff check .
uv run ruff format --check .

Type Checking#

labapi uses Pyright for static type checking.

uv run pyright

Continuous Integration#

GitHub Actions split the main quality gates into separate workflows under .github/workflows:

  • unit tests

  • lint

  • format

  • typecheck

  • docs

  • manual integration tests

Keeping these commands green locally is the fastest way to avoid CI surprises.

Type System#

labapi uses Python’s type system as a first-class tool rather than optional documentation. All new code should be fully type-annotated.

Key conventions:

  • from __future__ import annotations is present in every module.

  • Generics are used throughout the entry system so callers get concrete return types without extra casting.

  • TYPE_CHECKING guards prevent circular imports while keeping type information available to static checkers.

  • override is applied to method overrides so missing base methods are caught at check time.

  • overload is used on __getitem__ to express the different return types produced by different index kinds.

The project targets Python 3.12+ and uses modern syntax where it improves clarity, including type aliases, match statements, and Self.