Use Black formatting

[incaseoftrouble]

Hi,

This is more of a recommendation that would ease PR / Merging significantly: Namely, use / require the python formatter black. See here for its documentation.

Basically, black defines one very "rigid" code style, i.e. after formatting a file with black, it will almost always look the same, no matter what formatting one starts from. This may at first sound constricting, but if the style is so rigid, no formatting changes can accidentally creep into MRs and only "actual" changes appear in the PR.

Usage is quite simple. pip install black followed by black problemtools/ to format all .py files in that folder. So it also is rather simple to update all existing forks etc.

[Tagl]

An alternative is ruff

[incaseoftrouble]

Oh thanks, I didn't know that. I have no strong opinion on ruff over black, the main point of this issue is to suggest to use any of the reasonably popular formatters to have a defined formatting. This project is small enough that there probably isn't a noticeable difference between black and ruff, and its just about deciding whether it is a good idea (I really think so) and picking whichever seems more stable (both seem very mature).

[incaseoftrouble]

Bump on this: I "switched" most of my projects to ruff thanks to your suggestion @Tagl

For the sake of this issue: Note that ruff and black are the "same", in the sense that ruff does black formatting + a lot of other stuff. Using ruff is nice because it also does a lot of static analysis and quick fixes.

I can add ruff with a pre-commit hook / open a PR to see how the repo would look like with ruff applied.

[gkreitz]

I agree, I think ruff would make sense (both ruff format which this issue is about, and ruff check). I've done some test runs, and I think there are a few spots where it harms readability (one instance is verifyproblem.argparser_basic_arguments where most commands get spread out over multiple lines, but a few get squeezed onto a single line, making them easy to miss), but overall, it feels like a net positive.

Looking at the code, I feel like we commonly have long lines due to relatively long message strings, so I think we want a relatively high line length. From playing around with it and looking at how verifyproblem.py ends up, I felt like 130, while a bit of an odd choice, was a sweet spot. I think we use single quotes more often than double quotes (I sure know I do). So, I think something like this for config (in pyproject.toml):

[tool.ruff]
line-length = 130
exclude = [ "examples" ]

[tool.ruff.format]
quote-style = "single"

To get ruff in the repo, I assume we want to do something like:

• Fix stuff ruff check complains about (it all looked like reasonable stuff to fix) as a separate PR. I'm working on this.
• Decide on a ruff config (my proposal is above, but I'd love if people with more experience chime in)
• Do a ruff format of the code as a PR
• Add pre-commit hook and CI conf. I haven't played around with pre-commit at all. I'd very much prefer us to pin a version (including cryptographic hashes) to ensure the same version of ruff is run both at developers and in CI. Can pre-commit easily do that?

[incaseoftrouble]

• Agree with the points on ruff check
• On config, less is better. One main selling point of ruff is that it is very consistent and there aren't 20 different variants of its formatting. I think this config is fine (and if it turns out it needs tweaks its reasonably easy to change it)
• On applying ruff: Indeed, and on every open PR, too.
• Pre-commit is pleasantly easy!

Example .pre-commit-config.yml

repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.11.8
  hooks:
    - id: ruff
    - id: ruff-format

where for rev: one can also put a specific commit hash, then pre-commit install and done.

Note that pre-commit won't handle CI tasks (its not intended to do so, nor should CI apply the formatting, it should only check), one would need to run ruff check (or so) in CI (a GitHub action for ruff would be - uses: astral-sh/ruff-action@v3; this will take the ruff version from pyproject.toml). black / ruff emphasizes portability though, so minor version mismatches shouldn't be an issue.

[gkreitz]

Thank you!

#303 checks off points 1 and 2 on my list above, so once that's merged, I'll do a PR which is solely a ruff format (and probably throw in the pre-commit and CI conf in the same PR).

I took a look at home-assistant-core (which I generally feel is doing a lot of things well w.r.t. python development), and they seem to run ruff via pre-commit also in CI, https://github.com/home-assistant/core/blob/dev/.github/workflows/ci.yaml#L363 . That said, you're probably right that just using the ruff GitHub action is a good start, as the formatting should be very stable.

[incaseoftrouble]

Ah, indeed! They use pre-commit to run the ruff check, which is fine, too -- probably makes it a bit simpler to keep things consistent in such a large project. It doesn't make sense for the CI action to apply the pre-commit hook though (as that would apply the formatting instead of checking :-) )

(bloody hell, 1500 line CI script :D)

[gkreitz]

#304 does the formatting of the current repo.

(yeah, github action configs have huge overhead once you want everything in single steps, and caching, and the ability to toggle steps on/off depending on things. Feels like there are 50-100 lines for each actual command they run... :)