Dev code formatter

[timothy-holmes]

I had a crack at adding black the way @karosc suggested. Reverted changes to avoid conflicts with other PR.

Shell history (missing lines are git status or similar):

  49 black .\pyswmm --verbose
  51 git add .
  52 git commit -m "run black"
  53 git rev-parse --verify HEAD
  55 git add .\.git-blame-ignore-revs
  56 git commit -m "add black commit to .git-blame-ignore-revs"
  57 git config blame.ignoreRevsFile .git-blame-ignore-revs
  59 git blame .\pyswmm\simulation.py --ignore-revs-file .git-blame-ignore-revs
  61 git revert --no-commit HEAD
  65 git revert --no-commit HEAD~1
  67 git add .
  68 git commit -m "revert formatting"

I also added a GH Actions workflow to enforce formatting.

[karosc]

I think autoformatting is a great thing to have when working on an open source project. I'd like to prompt feedback from some of the other contributors to this project... @bemcdonnell. If we do want to go with blackening the code, I'd also advocate for adding a pre-commit.yaml file with the black hook in there.

[timothy-holmes]

I can add pre-commit, and update/refactor requirements.txt.

So, the intended workflow would be like this?

(fork)
git clone
git checkout
python -m venv
./activate # or equivalent
pip install -r requirements-dev.txt && pre-commit install
(do things)
git commit .. push .. PR

Happy to update the wiki after this.

[bemcdonnell]

@karosc many years ago we used autopep8. I didn’t mind it much and appreciated the always formatted code. I’m in favor of doing this again but I would like to run it locally with a standard tool instead of have a commit hook. The action should check if the formatter wasn’t run .. but I just want to be careful not to over complicate the contribution process.

[karosc]

@bemcdonnell, I wouldn't want the pre-commit github action running necessarily, just a convenient pre-commit.yaml file that would allow users to optionally install the git pre-commit hooks supported by the project. In this instance the black hook.

Pre-commit is a great tool to make sure your code is formatted and linted prior to creating any commit, but I don't think we need to force anyone to use it....the config would just be there for anyone who wants to install it. With ruff and black being so fast, running them on git commits it a very seamless experience and prevents linting workflows from failing in the cloud.

@timothy-holmes,

I can add pre-commit, and update/refactor requirements.txt.

So, the intended workflow would be like this?

(fork)
git clone
git checkout
python -m venv
./activate # or equivalent
pip install -r requirements-dev.txt && pre-commit install
(do things)
git commit .. push .. PR

Happy to update the wiki after this.

This looks like the right workflow, although I'd opt to put pre-commit in requirements-dev.txt

[bemcdonnell]

@karosc what are the next steps to wrap this PR up? I think the momentum was pretty nice to see :)

[karosc]

@bemcdonnell, next steps IMO would be to:

1. pump the entire repo through black and add to git in a single commit
2. create a .git-blame-ignore-revs file in the root directory of the project and add the commit hash of the wholesale formatting to the file (see xarray example)
3. commit the .git-blame-ignore-revs file to the repo.
4. add pre-commit yaml to repo that includes the psf black hook
5. merge after linting workflow passes

thoughts @timothy-holmes?

[bemcdonnell]

@karosc which one of us gets to take that massive commit?!? Do we arm wrestle for it? 😂😂

[timothy-holmes]

@karosc, @bemcdonnell: I did the blackening and subsquent .git-blame-ignore-revs in these commits: b09735f 9968cd5

Have a browse and see if there's anything you don't like. Eg. tests were included, double-quotes replaced single-quotes in many instances.

Otherwise, it's pretty much there.

[timothy-holmes]

Nm, I'll do it now