BLACK-PRIMER(1)

✨ black-primer(1) — the manual page, but make it cute ✨

okay bestie, sit down, hydrate, and let me tell you about black-primer — it's giving "CI tool energy" and honestly? obsessed. 🫶

---

💖 NAME 💖

black-primer — a CI tool to check a number of projects in parallel using black 🌸

---

🦋 DESCRIPTION 🦋

So black-primer is a tool built for CI (and for humans too, we love inclusivity 💜) to have black --check a whole bunch of Git accessible projects in parallel. Multiple. At once. Multitasking queen behavior 👑

And where do all these projects live? In a config file called primer.json. That's the plug, that's where you configure everything. periodt. 💅

---

🎀 RUN FLOW 🎀

Here's the whole vibe check, step by step:

• First things first: make sure we have black + git installed ✅ (git is literally mandatory bestie, it's giving prerequisites)
• Load 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 schematics)
• 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 this lil hack bestie, it's a game changer:

• Using -k / --keep + -w / --work-dir so you don't have to re-checkout the repo each run 🔥 (no cap, this saves you SO much time)

---

👑 CLI ARGUMENTS 👑

Behold, the usage text, verbatim, untouched, iconic:

Usage: black-primer [OPTIONS]

 primer - prime projects for blackening...

Options:
 -c, --config PATH      JSON config file path  [default: /Users/cooper/repos/
                        black/src/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]
 -R, --rebase           Rebase project if already checked out  [default:
                        False]

 -w, --workdir PATH     Directory path for repo checkouts  [default: /var/fol
                        ders/tc/hbwxh76j1hn6gqjd2n2sjn4j9k1glp/T/primer.20200
                        517125229]

 -W, --workers INTEGER  Number of parallel worker coroutines  [default: 2]
 -h, --help             Show this message and exit.

Let me break those flags down for you so you know exactly what you're tapping into 💅

• -c, --config PATH — the JSON config file path. default is /Users/cooper/repos/black/src/black_primer/primer.json 🗂️
• --debug — turn on debug logging. default: False
• -k, --keep — keep workdir + repos post run. default: False (yes, this is the speed-up trick from earlier ✨)
• -L, --long-checkouts — pull big projects to test. default: False 🐘
• -R, --rebase — rebase project if already checked out. default: False
• -w, --workdir PATH — directory path for repo checkouts. default: /var/folders/tc/hbwxh76j1hn6gqjd2n2sjn4j9k1glp/T/primer.20200517125229
• -W, --workers INTEGER — number of parallel worker coroutines. default: 2 👯
• -h, --help — show this message and exit. the classic. the icon. 🫶

---

🌈 Primer config file 🌈

The config file is in JSON format. Its main element is the "projects" dictionary, and each parameter is explained right here bestie, don't skip:

{
 "projects": {
   "00_Example": {
     "cli_arguments": "List of extra CLI arguments to pass Black for this project",
     "expect_formatting_changes": "Boolean to indicate that the version of Black is expected to cause changes",
     "git_clone_url": "URL you would pass `git clone` to check out this repo",
     "long_checkout": "Boolean to have repo skipped by default unless `--long-checkouts` is specified",
     "py_versions": "List of major Python versions to run this project with - all will do as you'd expect - run on ALL versions"
   },
   "aioexabgp": {
     "cli_arguments": [],
     "expect_formatting_changes": true,
     "git_clone_url": "https://github.com/cooperlees/aioexabgp.git",
     "long_checkout": false,
     "py_versions": ["all", "3.8"]
   }
 }
}

An example primer config file is used by Black [here](<https://github.com/psf/black/blob/master/src/black_primer/primer.json>) 💖 (go look, it's real, iykyk)

---

💀 EXAMPLE RUN 💀

here's what it actually looks like when you run it, raw and unfiltered:

cooper-mbp:black cooper$ ~/venvs/b/bin/black-primer
[2020-05-17 13:06:40,830] INFO: 4 projects to run Black over (lib.py:270)
[2020-05-17 13:06:44,215] INFO: Analyzing results (lib.py:285)
-- primer results 📊 --

3 / 4 succeeded (75.0%) ✅
1 / 4 FAILED (25.0%) 💩
 - 0 projects disabled by config
 - 0 projects skipped due to Python version
 - 0 skipped due to long checkout

Failed projects:

## flake8-bugbear:
 - Returned 1
 - stdout:
--- tests/b303_b304.py      2020-05-17 20:04:09.991227 +0000
+++ tests/b303_b304.py      2020-05-17 20:06:42.753851 +0000
@@ -26,11 +26,11 @@
     maxint = 5  # this is okay
     # the following should not crash
     (a, b, c) = list(range(3))
     # it is different than this
     a, b, c = list(range(3))
-    a, b, c, = list(range(3))
+    a, b, c = list(range(3))
     # and different than this
     (a, b), c = list(range(3))
     a, *b, c = [1, 2, 3, 4, 5]
     b[1:3] = [0, 0]

would reformat tests/b303_b304.py
Oh no! 💥 💔 💥
1 file would be reformatted, 22 files would be left unchanged.

look at that 💥 💔 💥 — the drama, the raw emotion, black really said "would reformat" and dipped. 😭

---

🌸 COPYRIGHT 🌸

Copyright 2018 Łukasz Langa

---

<div align="center">✨ 🦋 ✨</div>

okay that's the whole page bestie!! this one's version 21.4b2-2, and the page itself is dated 2021-10-10 💖 go check some projects in parallel, you absolute icon 👑 periodt 💅