Skip to content

How to work on ezxl locally

Use this guide to create a contributor-ready workspace with the current lint, typing, test, and packaging tooling.

🔧 Prerequisites

  • A cloned EzXl repository
  • uv installed locally
  • Python 3.11 or later

📝 Steps

  1. Sync the workspace with every contributor dependency group.

    pip install -e . --group dev

    uv sync --all-groups

    The groups follow PEP 735: test, docs, and dev (which includes both). pip install --group needs pip 25.1 or later.

  2. Install the git hooks managed by pre-commit.

    pre-commit install

    uv run pre-commit install

  3. Run the formatter and linter.

    ruff format src tests
ruff check src tests

    uv run poe format
uv run poe lint

  4. Run both configured type checkers.

    pyright
ty check

    uv run poe typecheck

  5. Enforce the import-layer contract.

    lint-imports

    uv run poe imports

  6. Run the test suite, then build the distributable artifacts.

    pytest -m "not excel"
python -m build
twine check dist/*

    uv run poe test-ci
uv run poe build
uv run twine check dist/*

    poe test-ci is exactly what CI runs: it deselects the excel marker (those tests drive a live Excel instance over COM) and applies the coverage threshold.

  7. Replay the whole gate in one command before opening a pull request.

    uv run poe check     # format-check -> lint -> typecheck -> imports -> test
uv run poe security  # bandit + pip-audit

Variations

If you only need the fast code-quality loop during feature work:

ruff check . --fix
ty check

uv run poe lint-fix
uv run poe typecheck

EzXl centralizes runtime-only pywintypes members in compatibility helpers so that ty and pyright can type-check the COM boundary without scattered local workarounds.

If you need to bump the release version, edit version under [project] in pyproject.toml — it is the single source of truth — then sync _version.py from it:

python .scripts/dev/update_version.py

uv run poe version

The sync-version pre-commit hook runs the same script, so a bump committed without this step is corrected at commit time.

✅ Result

You have a local workspace aligned with the repository tooling, including formatting, linting, type checking, import contract validation, packaging, and installed git hooks.