Use black?

Formatting the codebase with black would help in a few ways:

• avoid review nitpicks regarding style
• make signatures easier to read (when type annotations are involved, things can get really ugly)
• avoid PRs where contributors IDE automatically re-format the imports etc, and we always have to tell them to revert such unrelated changes
• help avoiding the CI linting issues
• overall style consistency

Cons:

• Adds noise to git blame, namely 1 extra click. This is for GitHub only, locally nothing is changed (see below)
• Adds a lot of vertical length to the code. It can be a bit unsettling/ugly at first, but you get used to it
• a bit more setup/work for new contributors, but black is becoming more and more of a standard anyway so people are mostly used to it, and pre-commit hooks are very easy to setup.
• will create conflicts with ongoing PRs. Not really a big deal, there aren’t too many PRs and resolving conflicts should be fairly simple
• As discovered with @pmeier, this forces to add a new --no-build-isolation to all pip install --editable commands [1], as done in https://github.com/pytorch/vision/pull/4178/commits/3d1cd1daf7412b2b7f5150d6ea47ce9bb109d1ee. This isn’t a big deal either as long as we provide good guidelines, and we recommend conda over pip anyway

Using black has already been discussed in https://github.com/pytorch/vision/issues/2025, with general positive sentiment towards adoption. The main concern seems to be that black brakes git blame, but it’s actually not the case: we can avoid breaking git glame thanks to the ignore-revs-file option (unfortunately, GitHub doesn’t support it yet, so the Github blame may still be a bit noisy).

[1] The reason for this nonsense is that black relies (only) on a pyproject.toml file for its configuration. This file was initially intended to declare build-time dependencies (something completely unrelated to code formatting, but oh well), and it can make pip behave differently in editable mode https://github.com/psf/black/issues/683#issuecomment-487306157, as illustrated in https://app.circleci.com/pipelines/github/pytorch/vision/9457/workflows/4007ced4-684c-498d-8c78-f6ee83853a7d/jobs/697466 . We need the –no-build-isolation flag to preserve pip’s sane behaviour, now that this file is added.

---

Adopting black would involve:

• a black-formatting PR (duh). Might consider make the PR author a bot or some dummy account.
• A PR that adds the ignore-revs-file file, referencing the previous PR for git-blame to be preserved.
• some instructions in the contributing guide to use black, edit the “install from source” docs with pip install -e . to use the --no-build-isolation flag, and optionally setup a pre-commit hook as done e.g. in pandas
• some instructions e.g. as a sticky issue to resolve potential merge conflicts
• a new CI check. This could just be part of the current job that checks for flake8.

I’m happy to work on this if we agree to rely on black from now on.

CC @fmassa @pmeier

[NicolasHug]

OK, so I tried internally and applying pyfmt is working fine and is consistent with the internal fb linter.

For it to be fully compliant we’ll need to add

[tool.usort]
first_party_detection = false

in the pyproject.toml.

Also, we need to pin down the dependencies as such:

➜  ~ pyfmt -V
fb-pyfmt built mode/opt (fastzip) on Python 3.8.3 (macosx-x86_64_minimal_xcode)
black version 21.4b2
usort version 0.6.4
libcst version 0.3.19

(This command can be run from any fb machine, whether it’s a laptop or a devvm).

[pmeier]

I’d just like to keep my contribution history clean, ideally 😃

If that is the only reason, I’m happy to create the PR. No need to bother setting up a new account or bot for this.