]> git.madduck.net Git - etc/vim.git/blob - docs/black_primer.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Only require typing-extensions if Python < 3.8 (#1873)
[etc/vim.git] / docs / black_primer.md
1 # black-primer
2
3 `black-primer` is a tool built for CI (and humans) to have _Black_ `--check` a number of
4 (configured in `primer.json`) Git accessible projects in parallel. _(A PR will be
5 accepted to add Mercurial support.)_
6
7 ## Run flow
8
9 - Ensure we have a `black` + `git` in PATH
10 - Load projects from `primer.json`
11 - Run projects in parallel with `--worker` workers (defaults to CPU count / 2)
12   - Checkout projects
13   - Run black and record result
14   - Clean up repository checkout _(can optionally be disabled via `--keep`)_
15 - Display results summary to screen
16 - Default to cleaning up `--work-dir` (which defaults to tempfile schemantics)
17 - Return
18   - 0 for successful run
19   - < 0 for environment / internal error
20   - \> 0 for each project with an error
21
22 ## Speed up runs 🏎
23
24 If you're running locally yourself to test black on lots of code try:
25
26 - Using `-k` / `--keep` + `-w` / `--work-dir` so you don't have to re-checkout the repo
27   each run
28
29 ## CLI arguments
30
31 ```text
32 Usage: black-primer [OPTIONS]
33
34   primer - prime projects for blackening... 🏴
35
36 Options:
37   -c, --config PATH      JSON config file path  [default: /Users/cooper/repos/
38                          black/src/black_primer/primer.json]
39
40   --debug                Turn on debug logging  [default: False]
41   -k, --keep             Keep workdir + repos post run  [default: False]
42   -L, --long-checkouts   Pull big projects to test  [default: False]
43   -R, --rebase           Rebase project if already checked out  [default:
44                          False]
45
46   -w, --workdir PATH     Directory path for repo checkouts  [default: /var/fol
47                          ders/tc/hbwxh76j1hn6gqjd2n2sjn4j9k1glp/T/primer.20200
48                          517125229]
49
50   -W, --workers INTEGER  Number of parallel worker coroutines  [default: 2]
51   -h, --help             Show this message and exit.
52 ```
53
54 ## Primer config file
55
56 The config file is in JSON format. Its main element is the `"projects"` dictionary and
57 each parameter is explained below:
58
59 ```json
60 {
61   "projects": {
62     "00_Example": {
63       "cli_arguments": "List of extra CLI arguments to pass Black for this project",
64       "expect_formatting_changes": "Boolean to indicate that the version of Black is expected to cause changes",
65       "git_clone_url": "URL you would pass `git clone` to check out this repo",
66       "long_checkout": "Boolean to have repo skipped by default unless `--long-checkouts` is specified",
67       "py_versions": "List of major Python versions to run this project with - all will do as you'd expect - run on ALL versions"
68     },
69     "aioexabgp": {
70       "cli_arguments": [],
71       "expect_formatting_changes": true,
72       "git_clone_url": "https://github.com/cooperlees/aioexabgp.git",
73       "long_checkout": false,
74       "py_versions": ["all", "3.8"]
75     }
76   }
77 }
78 ```
79
80 An example primer config file is used by Black
81 [here](https://github.com/psf/black/blob/master/src/black_primer/primer.json)
82
83 ## Example run
84
85 ```console
86 cooper-mbp:black cooper$ ~/venvs/b/bin/black-primer
87 [2020-05-17 13:06:40,830] INFO: 4 projects to run Black over (lib.py:270)
88 [2020-05-17 13:06:44,215] INFO: Analyzing results (lib.py:285)
89 -- primer results 📊 --
90
91 3 / 4 succeeded (75.0%) ✅
92 1 / 4 FAILED (25.0%) 💩
93  - 0 projects disabled by config
94  - 0 projects skipped due to Python version
95  - 0 skipped due to long checkout
96
97 Failed projects:
98
99 ## flake8-bugbear:
100  - Returned 1
101  - stdout:
102 --- tests/b303_b304.py  2020-05-17 20:04:09.991227 +0000
103 +++ tests/b303_b304.py  2020-05-17 20:06:42.753851 +0000
104 @@ -26,11 +26,11 @@
105      maxint = 5  # this is okay
106      # the following should not crash
107      (a, b, c) = list(range(3))
108      # it is different than this
109      a, b, c = list(range(3))
110 -    a, b, c, = list(range(3))
111 +    a, b, c = list(range(3))
112      # and different than this
113      (a, b), c = list(range(3))
114      a, *b, c = [1, 2, 3, 4, 5]
115      b[1:3] = [0, 0]
116
117 would reformat tests/b303_b304.py
118 Oh no! 💥 💔 💥
119 1 file would be reformatted, 22 files would be left unchanged.
120 ```