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"] // "all" ignores all other versions
  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 shouldn't crash
 107      (a, b, c) = list(range(3))
 108      # it's 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 ```