- The main Python package/CLI lives in
calkit - The JupyterLab extension lives in
src - The VS Code extension lives in
vscode-ext
See CONTRIBUTING.md for tool usage, style guidelines, etc.
To run tests, use uv run pytest.
To sync the docs and format all the code, run make format.
Before finishing a change, type-check it. The CLI gate is mypy
(uv run mypy <changed files>, or make check for the full suite), and the
VS Code editor uses Pylance (Pyright). Keep new code clean under both, and do
not introduce new type errors.
Wrap prose at natural breakpoints in phrases or punctuation to keep max line length below 80 characters.
In the docs, MkDocs Material admonitions (!!! note, !!! tip, etc.) must be
preceded by a <!-- prettier-ignore --> comment. Otherwise Prettier reformats
the block and strips the 4-space indentation of the admonition body, which
breaks rendering.
Agents should never make commits to Git.
Prefer tests that include multiple scenarios to comprehensively test a feature in one function over many different test functions.
Do not write docstrings in test functions.
Do not put blank lines inside function bodies; separate logical sections with comments instead. This only applies to blank lines we write, not ones the formatter inserts, e.g., ruff-format adds one after an in-function import block. Don't hoist imports to module scope just to avoid those; imports are kept inside functions to keep CLI startup fast.
For prose, only use one space after punctuation.
Don't overzealously split up functions just because they're long. Functions should usually be used ~3 times before abstracting. Otherwise, split up long ones into logical sections with comments. The only exception here is if splitting up a function makes it easier to write meaningful unit tests. If a function is only used inside one other function, nest it inside the caller at the top.
No spaces on either side of en or em dashes used for ranges or pauses in prose, respectively.