Python Code Style

Last modified: 2026-11-16 08:38:31 (PST)

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.toml in the Morrison-Lab/psc repository. Copy it to the root of a repository as ruff.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’s check-python-package workflow in every repository that contains Python.
  • Run check-python-qmd-chunks in every repository whose .qmd files contain Python chunks.
  • Open an issue when upstream changes Google’s guide.

These are tracked in #90.