bindings: python: format and lint examples and other files

[vfazio]

Right now, we only format and lint the core library and the test suite per pyproject.toml settings.

These were reasonable targets early on to make sure the contract we were establishing followed set guidelines and to make sure we conformed to restrictions appropriate to the versions of python supported by the library.

I think it makes sense to expand the scope to include all supported files in the directory. This includes examples, setup.py, and build_tests.py.

[vfazio]

https://github.com/vfazio/libgpiod/actions/runs/23825270066?pr=4

[vfazio]

Sent a series to the mailing list. After posting, i realized that i was a lazy POS and didn't do a cover letter.

https://lore.kernel.org/linux-gpio/20260401001459.19159-1-vfazio@gmail.com/T/#t

[brgl]

No worries, I'll review as is.

[vfazio]

No worries, I'll review as is.

I typo'd in my email instructions, the below should work:

$ cd bindings/python
$ python3 -m venv venv
$ . venv/bin/activate
$ pip install -U pip
$ pip install --group lint
$ mypy --strict; ruff format; ruff check

Example:

vfazio@vfazio4:~/development/libgpiod-freethread/bindings/python$ . .venv/bin/activate
(.venv) vfazio@vfazio4:~/development/libgpiod-freethread/bindings/python$ pip install -U pip
Looking in indexes: https://nexus.xes-mad.com/repository/upstream-pypi/simple, https://nexus.xes-mad.com/repository/xes-pypi/simple
Requirement already satisfied: pip in ./.venv/lib/python3.14t/site-packages (26.0.1)
(.venv) vfazio@vfazio4:~/development/libgpiod-freethread/bindings/python$ pip install --group lint
Looking in indexes: https://nexus.xes-mad.com/repository/upstream-pypi/simple, https://nexus.xes-mad.com/repository/xes-pypi/simple
Requirement already satisfied: mypy>=1.18.1 in ./.venv/lib/python3.14t/site-packages (1.19.1)
Requirement already satisfied: ruff~=0.15.0 in ./.venv/lib/python3.14t/site-packages (0.15.8)
Requirement already satisfied: types-setuptools in ./.venv/lib/python3.14t/site-packages (82.0.0.20260210)
Requirement already satisfied: packaging in ./.venv/lib/python3.14t/site-packages (26.0)
Requirement already satisfied: typing_extensions>=4.6.0 in ./.venv/lib/python3.14t/site-packages (from mypy>=1.18.1) (4.15.0)
Requirement already satisfied: mypy_extensions>=1.0.0 in ./.venv/lib/python3.14t/site-packages (from mypy>=1.18.1) (1.1.0)
Requirement already satisfied: pathspec>=0.9.0 in ./.venv/lib/python3.14t/site-packages (from mypy>=1.18.1) (1.0.4)
Requirement already satisfied: librt>=0.6.2 in ./.venv/lib/python3.14t/site-packages (from mypy>=1.18.1) (0.8.1)
(.venv) vfazio@vfazio4:~/development/libgpiod-freethread/bindings/python$ mypy --strict; ruff format; ruff check
Success: no issues found in 46 source files
46 files left unchanged
All checks passed!

[vfazio]

merged

[brgl]

Hi! I just noticed that ruff now removes the newline between the class definition and the first method of it. Any chance we could configure it to leave that blank line in place for better readability?

After this series:

class LineRequestSurvivesParentChip(TestCase):
    def test_line_request_survives_parent_chip(self) -> None:
        sim = gpiosim.Chip()

I would love it to be:

class LineRequestSurvivesParentChip(TestCase):

    def test_line_request_survives_parent_chip(self) -> None:
        sim = gpiosim.Chip()

[vfazio]

Hi! I just noticed that ruff now removes the newline between the class definition and the first method of it. Any chance we could configure it to leave that blank line in place for better readability?

After this series:

class LineRequestSurvivesParentChip(TestCase):
    def test_line_request_survives_parent_chip(self) -> None:
        sim = gpiosim.Chip()

I would love it to be:

class LineRequestSurvivesParentChip(TestCase):

    def test_line_request_survives_parent_chip(self) -> None:
        sim = gpiosim.Chip()

@brgl interesting find... Here's what I know:

Black actually didn't follow your requested formatting for a while but then changed their mind:
psf/black#619
psf/black#4130

Since Ruff largely adheres to black it doesn't surprise me that there is lag or even disagreement here. This seems to be driven by purists of PEP 8 reading the method definition callout here https://peps.python.org/pep-0008/#blank-lines

Ruff has an open issue:
astral-sh/ruff#21380

Known deviations from black: https://docs.astral.sh/ruff/formatter/black/#blank-lines-at-the-start-of-a-block

Note that black > 24 doesn't reformat and insert the blank line if it's not already there. The rule seems to just allow an empty line, so there could be inconsistencies in class definitions across the code base due to this flexibility

(venv) I have no name!@vfazio4:~/development/libgpiod/bindings/python$ cat test.py 
class Test:
    variable = 1


class Test1:
    def fn(self):
        return 2


class Test2:

    variable = 1


class Test3:

    def fn(self):
        return 2
(venv) I have no name!@vfazio4:~/development/libgpiod/bindings/python$ black test.py
All done! ✨ 🍰 ✨
1 file left unchanged.
(venv) I have no name!@vfazio4:~/development/libgpiod/bindings/python$ black --version
black, 26.3.1 (compiled: yes)
Python (CPython) 3.12.3

"More readable" is a bit subjective I suppose. I often find having the first interesting thing immediately after the class definition directly after its declaration so it's concise and clear:

class Test:
    variable = 1

vs

class Test2:

    variable = 1

In this case, I think I personally prefer Ruff's current formatting, but we can probably get somewhat of a compromise if we leverage empty docstrings or actually document the intent of the classes.

(venv) I have no name!@vfazio4:~/development/libgpiod/bindings/python$ git diff
diff --git a/bindings/python/tests/tests_line_request.py b/bindings/python/tests/tests_line_request.py
index 8cb0f2c..af82d0a 100644
--- a/bindings/python/tests/tests_line_request.py
+++ b/bindings/python/tests/tests_line_request.py
@@ -659,6 +659,7 @@ class ReleasedLineRequestCannotBeUsed(TestCase):
 
 
 class LineRequestSurvivesParentChip(TestCase):
+    """"""
     def test_line_request_survives_parent_chip(self) -> None:
         sim = gpiosim.Chip()

(venv) I have no name!@vfazio4:~/development/libgpiod/bindings/python$ ruff format --diff
--- tests/tests_line_request.py
+++ tests/tests_line_request.py
@@ -660,6 +660,7 @@
 
 class LineRequestSurvivesParentChip(TestCase):
     """"""
+
     def test_line_request_survives_parent_chip(self) -> None:
         sim = gpiosim.Chip()
 

1 file would be reformatted, 45 files already formatted

Of course, as I test this, even docstrings are inconsistent. I noticed that using docstrings on methods doesn't force a blank line afterwards. That seems to only be enforced at the class level... but should enable the visible line break you prefer with the current ruleset.

Voicing support in astral-sh/ruff#21380 seems like probably the best way to get this behavior introduced without having to rely on the docstring hack.

[brgl]

Thanks for the investigation! I can live with it I guess, I thought it's configurable.