Cython Lint

0.19.0 · active · verified Mon Apr 13

cython-lint is a powerful static analysis tool and pre-commit hook designed to lint Cython files. It extends the capabilities typically found in Python linters like flake8 to the Cython language, helping developers maintain code quality and catch common pitfalls. The current version is 0.19.0, with a release cadence of several minor versions per year.

Warnings

gotcha cython-lint flags unused variables and imports. Messages like ''variable defined but unused'' or ''imported but unused'' indicate code that can be cleaned up, similar to Python linters.
Fix: Remove the unused variable, function, or import, or prefix unused variables with an underscore (e.g., `_x`) to signal intentional non-use.
gotcha Dangerous mutable default values in function arguments are flagged (e.g., `def func(arg=[]):`). This common Python footgun extends to Cython functions.
Fix: Use immutable default values (e.g., `None`) and initialize mutable objects inside the function body (e.g., `arg = [] if arg is None else arg`).
gotcha By default, cython-lint includes `pycodestyle` checks, which may report Python-specific style issues. If these are not desired, they can be disabled.
Fix: Use the `--no-pycodestyle` command-line flag or configure `no-pycodestyle = true` in `.cython-lint.toml` or `pyproject.toml` to disable `pycodestyle` checks.
breaking cython-lint requires Python 3.10 or newer. Attempting to install or run on older Python versions will result in an installation or runtime error.
Fix: Ensure your environment uses Python 3.10 or a newer compatible version.
gotcha Relative imports can lead to complex module resolution issues in Python and Cython. `cython-lint` introduced a `--ban-relative-imports` flag in v0.17.0 to help enforce absolute imports.
Fix: Prefer absolute imports over relative imports. If necessary, enable the `--ban-relative-imports` flag to prevent them, or refactor your module structure.

Install

pip install cython-lint Install stable version

Imports

cython_lint
```
Usage is primarily via the command-line interface or as a pre-commit hook.
```
cython-lint is designed for command-line use; a stable, public Python API for direct programmatic linting of arbitrary code is not widely documented or intended for general use.

Quickstart

To quickly lint a Cython file from the command line, create a `.pyx` file and run `cython-lint` against it. This example demonstrates detection of an unused variable and an 'always true' tuple condition.

echo "def foo():\n    x = 1 # unused variable\n    if (1,): pass # always true tuple condition\n    l = []\n    l.append(1)" > my_module.pyx
cython-lint my_module.pyx

view raw JSON →