pycodestyle

Checks against PEP-8 style guidelines.

PyPI View on PyPI GitHub View on GitHub Conda View on Conda

Example Quarto .qmd file:

1:     ---
2:     title: "Example"
3:     ---
4:     
5:     This file contains some issues for the linter to identify.
6:     
7:     ```{python}
8:     very_long_line = "This long string exceeds the maximum allowed characters per line."
9:     ```
10:    
11:    There's some more issues below...
12:    
13:    ```{python}
14:    def add_numbers(a, b):
15:        return a + b
16:    
17:    add_numbers(3, 5)
18:    
19:    import sys
20:    ```

Run pycodestyle using lintquarto

lintquarto -l pycodestyle -p general_example.qmd
==========================================================
Running pycodestyle...
==========================================================
/home/runner/work/lintquarto/lintquarto/docs/pages/tools/examples/general_example.qmd:14:1: E302 expected 2 blank lines, found 0
/home/runner/work/lintquarto/lintquarto/docs/pages/tools/examples/general_example.qmd:17:1: E305 expected 2 blank lines after class or function definition, found 1
/home/runner/work/lintquarto/lintquarto/docs/pages/tools/examples/general_example.qmd:19:1: E402 module level import not at top of file

Known limitation for pycodestyle with lintquarto

lintquarto works by converting .qmd files into temporary .py files. During this process, non-code regions (e.g., markdown and cell boundaries) are replaced with placeholder lines (# -) so that line numbers remain aligned between the original .qmd file and the generated .py file. Linters are then run on the generated Python file.

This approach causes issues with pycodestyle for the E3xx “blank line/layout” rules (e.g., E302, E305). The inserted placeholder lines can cause pycodestyle to report false positive violations of these rules - as can be seen in the example above. While these false positives can be suppressed by lintquarto for other packages using # noqa,pycodestyle only supports # noqa for a limited subset of error codes and does not allow suppression of E3xx rules in this way. As a result, these false positives cannot be reliably ignored when using pycodestyle directly. This is a known limitation (#142).

Work around

If you want to apply pycodestyle checks to Quarto files without these false positives, we recommend using a wrapper tool like flake8 or ruff. These tools include pycodestyle rules but allow suppression of E3xx rules via # noqa, making it possible to ignore the conversion-related violations.

Flake8: You can restrict checks to pycodestyle rules via setup.cfg:

# setup.cfg
[flake8]
select = E,W

Ruff: You can restrict checks to pycodestyle rules via pyproject.toml:

# pyproject.toml
[tool.ruff.lint]
extend-select = ["E", "W"]