# Python

> Lint, format, type-check, and test Python projects.

gspot checks Python with Ruff for lint and format, basedpyright, import-linter, pydoclint, and deptry, plus built-in checks. These checks run for the `python` configuration:

| Check                                                                               | Stage    | What it does                                                                                                 |
| ----------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| [`python/ruff`](/reference/checks/python/ruff/)                                     | `commit` | Lints every Python file with the Ruff rules for the level, security rules included.                          |
| [`python/ruff-format`](/reference/checks/python/ruff-format/)                       | `commit` | Checks the layout of every Python file against the Ruff formatter.                                           |
| [`python/basedpyright`](/reference/checks/python/basedpyright/)                     | `push`   | Type checks the project. At level `all`, it also requires annotations.                                       |
| [`python/import-linter`](/reference/checks/python/import-linter/)                   | `commit` | Runs project import contracts from setup.cfg, .importlinter, or pyproject.toml.                              |
| [`python/pydoclint`](/reference/checks/python/pydoclint/)                           | `commit` | Checks that each docstring names the arguments, return value, and exceptions of its function.                |
| [`python/deptry`](/reference/checks/python/deptry/)                                 | `push`   | 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` | 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` | Finds docstrings that hold a placeholder word, or the name of the function again.                            |

## Before you start

Install gspot with mise, as the [Quickstart](/start/quickstart/) shows for a repository without `package.json`. Use uv for your project. basedpyright and pytest read the `.venv` of the project, so sync it before you run the checks:

```shell
uv sync
```

## Docstring style

pydoclint takes its docstring style from the first source that sets one:

1. A `[tool.pydoclint]` style in `pyproject.toml`.
2. The pydocstyle convention in the Ruff options of the project.
3. `tools.ruff.docstring_convention`, when it equals `google` or `numpy`.
4. Google or NumPy sections that gspot finds in your docstrings.

Otherwise, pydoclint uses its default.

## Tests

[Tests and coverage](/checks/testing/#python-with-pytest) covers pytest.