Gauging changes¶
A lot of the time, your change will affect formatting and/or performance. Quantifying these changes is hard, so we have tooling to help make it easier.
It’s recommended you evaluate the quantifiable changes your Black formatting modification causes before submitting a PR. Think about if the change seems disruptive enough to cause frustration to projects that are already “black formatted”.
black-primer¶
black-primer
is a tool built for CI (and humans) to have Black --check
a number of
Git accessible projects in parallel. (configured in primer.json
) (A PR will be
accepted to add Mercurial support.)
Run flow¶
Ensure we have a
black
+git
in PATHLoad projects from
primer.json
Run projects in parallel with
--worker
workers (defaults to CPU count / 2)Checkout projects
Run black and record result
Clean up repository checkout (can optionally be disabled via
--keep
)
Display results summary to screen
Default to cleaning up
--work-dir
(which defaults to tempfile schemantics)Return
0 for successful run
< 0 for environment / internal error
> 0 for each project with an error
Speed up runs 🏎¶
If you’re running locally yourself to test black on lots of code try:
Using
-k
/--keep
+-w
/--work-dir
so you don’t have to re-checkout the repo each run
CLI arguments¶
Usage: black-primer [OPTIONS]
primer - prime projects for blackening... 🏴
Options:
-c, --config PATH JSON config file path [default: /home/docs/checkouts
/readthedocs.org/user_builds/ichard26-testblackdocs/e
nvs/issue-triage-docs/lib/python3.8/site-
packages/black_primer/primer.json]
--debug Turn on debug logging [default: False]
-k, --keep Keep workdir + repos post run [default: False]
-L, --long-checkouts Pull big projects to test [default: False]
--no-diff Disable showing source file changes in black output
[default: False]
-R, --rebase Rebase project if already checked out [default:
False]
-w, --workdir PATH Directory path for repo checkouts [default:
/tmp/primer.20210516160411]
-W, --workers INTEGER Number of parallel worker coroutines [default: 2]
-h, --help Show this message and exit.