# python

> Python sources: lint, layout, strict types, import contracts, docstrings that match their signatures, and no unused code or dependencies.

Python sources: lint, layout, strict types, import contracts, docstrings that match their signatures, and no unused code or dependencies. The [Python guide](/languages/python/) explains the setup.

## Checks

| Check                                                                               | Stage    | Level         | What it does                                                                                                 |
| ----------------------------------------------------------------------------------- | -------- | ------------- | ------------------------------------------------------------------------------------------------------------ |
| [`python/ruff`](/reference/checks/python/ruff/)                                     | `commit` | `recommended` | Lints every Python file with the Ruff rules for the level, security rules included.                          |
| [`python/ruff-format`](/reference/checks/python/ruff-format/)                       | `commit` | `recommended` | Checks the layout of every Python file against the Ruff formatter.                                           |
| [`python/basedpyright`](/reference/checks/python/basedpyright/)                     | `push`   | `recommended` | Type checks the project. At level `all`, it also requires annotations.                                       |
| [`python/import-linter`](/reference/checks/python/import-linter/)                   | `commit` | `recommended` | Runs project import contracts from setup.cfg, .importlinter, or pyproject.toml.                              |
| [`python/pydoclint`](/reference/checks/python/pydoclint/)                           | `commit` | `recommended` | Checks that each docstring names the arguments, return value, and exceptions of its function.                |
| [`python/deptry`](/reference/checks/python/deptry/)                                 | `push`   | `recommended` | Compares the imports of the project with the dependencies it declares: missing, unused, and transitive ones. |
| [`python/pip-installs`](/reference/checks/python/pip-installs/)                     | `commit` | `all`         | Checks that pyproject.toml lists every dependency, with no hand-kept requirements file and no `pip install`. |
| [`python/placeholder-docstrings`](/reference/checks/python/placeholder-docstrings/) | `commit` | `all`         | Finds docstrings that hold a placeholder word, or the name of the function again.                            |

## Settings

| Setting                                                                                     | What it sets                                                                 |
| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [`tools.ruff.docstring_convention`](/reference/gspot-toml/#tools.ruff.docstring_convention) | The docstring style that Ruff and pydoclint check: google, numpy, or pep257. |

## Selected when

gspot selects it in a scope with file extensions `.py`, or script interpreters `python`, `python3`, or project files `pyproject.toml`, `requirements*.txt`, `Pipfile`. A configuration that requires it selects it too: [`fastapi`](/reference/configurations/fastapi/), [`pytest`](/reference/configurations/pytest/).

## Rules for coding agents

| Rule file                                                  | Installed when |
| ---------------------------------------------------------- | -------------- |
| `.gspot/configurations/language/python/rules/DESIGN.md`    | Always         |
| `.gspot/configurations/language/python/rules/FLOW.md`      | Always         |
| `.gspot/configurations/language/python/rules/PACKAGING.md` | Always         |
| `.gspot/configurations/language/python/rules/PYTHON.md`    | Always         |
| `.gspot/configurations/language/python/rules/TYPING.md`    | Always         |

## Tools and versions

| Tool         | Version   |
| ------------ | --------- |
| uv           | `0.12.22` |
| ruff         | `0.16.8`  |
| basedpyright | `1.40.1`  |
| lint-imports | `2.15`    |
| pydoclint    | `0.9.1`   |
| deptry       | `0.25.1`  |

## Files gspot writes

gspot writes `.gspot/configurations/language/python/ruff.toml` and `.gspot/configurations/language/python/basedpyright.json`.

## Kept out of Git

`.venv` and `venv`.