Python Code Style
1 Base guide
The lab’s Python style is an amendment of Google’s Python style guide, read in the lab’s fork at a pinned commit. Follow that guide for everything the amendments below do not change. Google’s current wording is at google.github.io/styleguide/pyguide.html.
2 Amendments
2.1 Linting and formatting with Ruff
Ruff replaces the pylint configuration and the Pyink formatter that Google’s guide mentions. It lints and formats in one tool.
- Lint settings live in the lab’s
python/ruff.tomlin theMorrison-Lab/pscrepository. Copy it to the root of a repository asruff.toml. - Line length stays at 80 characters, as in Google’s guide.
- Docstrings follow Google’s format.
- Rule families are pycodestyle, pyflakes, isort, pydocstyle, pyupgrade, bugbear, comprehensions and simplify.
CI runs the checks and fails on any finding.
2.2 No nested function calls
The lab’s no-nested-calls rule applies to Python. Give each intermediate result a name. Method chaining is fine. Ruff cannot check this rule, so it is not yet enforced.
2.3 Figures with plotnine and plotly
Draw 2-D figures with plotnine, a Python implementation of the grammar of graphics. Its calls mirror the lab’s ggplot2 code, so a figure reads the same in R and in Python, and the lab’s qnp theme carries over. Draw 3-D figures with plotly, because plotnine draws no 3-D graphics. Do not use Matplotlib directly for figures in new code. Name every argument, including those inside aes(), as the name-arguments rule says for R. Convert existing Matplotlib figures in their own PRs, not in unrelated ones.
3 Planned work
- Run the checks through
Morrison-Lab/gha’scheck-python-packageworkflow in every repository that contains Python. - Run
check-python-qmd-chunksin every repository whose.qmdfiles contain Python chunks. - Open an issue when upstream changes Google’s guide.
These are tracked in #90.