add auto-formatter (`black`, `yapf`, etc) to GH actions

[OwenPriceSkelly]

as a collaborator on the garden project and a natural pedant, I dislike reading or writing code which is poorly-formatted, and the worst kind of formatting is the inconsistent kind. To ease the cognitive (and emotional) burden of reading or writing poorly-formatted code, we should add a GH action to format the code automatically before the repository is tainted

I currently use black locally, but would be happy to switch to yapf or something else more configurable to accommodate any strongly-held opinions.

Acceptance Criteria

Given proposed changes in a PR, when running GH actions (sometime before the flake8 check), the changes should be formatted by an auto-formatter such as black to be stylistically consistent with the rest of the codebase

[steve-barnard]

@OwenPriceSkelly have you all decided on which format to use (looked like it might have been black)? Also would having a pre-commit hook for formatting be an option? I have seen the pre-commit formatting work well, as this led to fewer issues when formatting conflicts occurred if someone pushed and forgot to pull back in the linted/formatted code.

Actions: https://black.readthedocs.io/en/stable/integrations/github_actions.html

Pre-Commit: https://black.readthedocs.io/en/stable/integrations/source_version_control.html

[blaiszik]

Let's discuss this on Tuesday at the Gathertown meeting. I've noticed, esp in some other repos that our commits are really large when only a few lines are actually changed. We should just pick one as a team and go with it :)

[OwenPriceSkelly]

agreed! especially like the idea of having it as a pre-commit hook. Super open to alternatives, but at this point I think it's probably the path of least resistance to just use black if that's tolerable to everyone

[steve-barnard]

Sounds good! If there is any way to share any current configs for the formatting that would be amazing; I know that when using flake8 and black there can be conflicting information on things like line length etc. Would love to know if there are any current examples of parameters you plan on using such as line length set to 79 or black's 88 or if we are ignoring any other formatting rules;

https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length

Was curious if the line length issues would cause any flake8 errors and cause the build to not complete.

I'm sure this is not a massive priority but would likely allow us to get something set up in the actions workflow as well as document the standards for any future contributors.

[OwenPriceSkelly]

That's a good idea - we might want to document this in a CONTRIBUTING.md or something, but in the meantime / for posterity:

• black is the auto formatter of choice as of #72 merging into main; in the spirit of the tool there is (currently) no additional configuration, but if we ever do tweak anything it'll be in pyproject.toml
• isort is not currently part of any pre-commit hook (since black already formats imports) but is pinned to a recent version and configured in pyproject.toml to play nice with black anyways, so anyone who uses isort or has their editor configured to do so shouldn't have to do anything special
• flake8 is configured in .flake8 to ignore whitespace before colons, because black's formatting of slices would give false positives
  • flake8 is also configured to use a line length of 150 -- I'm not sure where that number came from, but I think it's reasonable for edge cases like docstrings or whatever else black won't automatically line break at 88. Assuming the pre-commit hooks run, that's the only case (afaik) where the flake8 step in the ci build would fail

(closing this because I forgot to when I merged #72)