Add black-primer docs (#1427)
* Add `black-primer` docs - Document the idea, CLI args, config and a example run for `black-primer` in README.md - Add to docs/index.rst * Add @hugovk suggestions - Thanks.
This commit is contained in:
Cooper Lees
GitHub
parent
f62f1ddc2f
commit
b0f3798aab
135
README.md
135
README.md
@ -33,9 +33,10 @@ Try it out now using the [Black Playground](https://black.now.sh). Watch the
|
||||
_Contents:_ **[Installation and usage](#installation-and-usage)** |
|
||||
**[Code style](#the-black-code-style)** | **[Pragmatism](#pragmatism)** |
|
||||
**[pyproject.toml](#pyprojecttoml)** | **[Editor integration](#editor-integration)** |
|
||||
**[blackd](#blackd)** | **[Version control integration](#version-control-integration)**
|
||||
| **[Ignoring unmodified files](#ignoring-unmodified-files)** | **[Used by](#used-by)**
|
||||
| **[Testimonials](#testimonials)** | **[Show your style](#show-your-style)** |
|
||||
**[blackd](#blackd)** | **[black-primer](#black-primer)** |
|
||||
**[Version control integration](#version-control-integration)** |
|
||||
**[Ignoring unmodified files](#ignoring-unmodified-files)** | **[Used by](#used-by)** |
|
||||
**[Testimonials](#testimonials)** | **[Show your style](#show-your-style)** |
|
||||
**[Contributing](#contributing-to-black)** | **[Change Log](#change-log)** |
|
||||
**[Authors](#authors)**
|
||||
|
||||
@ -52,7 +53,7 @@ run but you can reformat Python 2 code with it, too.
|
||||
|
||||
To get started right away with sensible defaults:
|
||||
|
||||
```
|
||||
```sh
|
||||
black {source_file_or_directory}
|
||||
```
|
||||
|
||||
@ -1068,7 +1069,7 @@ Options:
|
||||
There is no official blackd client tool (yet!). You can test that blackd is working
|
||||
using `curl`:
|
||||
|
||||
```
|
||||
```sh
|
||||
blackd --bind-port 9090 & # or let blackd choose a port
|
||||
curl -s -XPOST "localhost:9090" -d "print('valid')"
|
||||
```
|
||||
@ -1117,6 +1118,124 @@ Apart from the above, `blackd` can produce the following response codes:
|
||||
The response headers include a `X-Black-Version` header containing the version of
|
||||
_Black_.
|
||||
|
||||
## black-primer
|
||||
|
||||
`black-primer` is a tool built for CI (and huumans) to have _Black_ `--check` a number
|
||||
of (configured in `primer.json`) Git accessible projects in parallel. _(A PR will be
|
||||
accepted to add Mercurial support.)_
|
||||
|
||||
### Run flow
|
||||
|
||||
- Ensure we have a `black` + `git` in PATH
|
||||
- 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 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
|
||||
|
||||
```text
|
||||
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: 69]
|
||||
-h, --help Show this message and exit.
|
||||
```
|
||||
|
||||
### primer config file
|
||||
|
||||
The config is `JSON` format. It's main element is the `"projects"` dictionary. Below
|
||||
explains each parameter:
|
||||
|
||||
```json
|
||||
{
|
||||
"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 defauult 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"] // "all" ignores all other versions
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example run
|
||||
|
||||
```console
|
||||
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 shouldn't crash
|
||||
(a, b, c) = list(range(3))
|
||||
# it's 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.
|
||||
```
|
||||
|
||||
## Version control integration
|
||||
|
||||
Use [pre-commit](https://pre-commit.com/). Once you
|
||||
@ -1170,10 +1289,10 @@ then write the above files to `.cache/black/<version>/`.
|
||||
|
||||
The following notable open-source projects trust _Black_ with enforcing a consistent
|
||||
code style: pytest, tox, Pyramid, Django Channels, Hypothesis, attrs, SQLAlchemy,
|
||||
Poetry, PyPA applications (Warehouse, Pipenv, virtualenv), pandas, Pillow, every Datadog
|
||||
Agent Integration, Home Assistant.
|
||||
Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow,
|
||||
every Datadog Agent Integration, Home Assistant.
|
||||
|
||||
The following organizations use _Black_: Dropbox.
|
||||
The following organizations use _Black_: Facebook, Dropbox.
|
||||
|
||||
Are we missing anyone? Let us know.
|
||||
|
||||
|
||||
@ -54,6 +54,7 @@ Contents
|
||||
pyproject_toml
|
||||
editor_integration
|
||||
blackd
|
||||
black-primer
|
||||
version_control_integration
|
||||
ignoring_unmodified_files
|
||||
contributing
|
||||
|
||||
Loading…
Reference in New Issue
Block a user