Loading README.md +127 −8 Changes for README.md: 127 added lines, 8 removed lines. Original line number Diff line number Diff line Loading @@ -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)** Loading @@ -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} ``` Loading Loading @@ -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')" ``` Loading Loading @@ -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 Loading Loading @@ -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. Loading docs/index.rst +1 −0 Changes for docs/index.rst: 1 added line, 0 removed lines. Original line number Diff line number Diff line Loading @@ -54,6 +54,7 @@ Contents pyproject_toml editor_integration blackd black-primer version_control_integration ignoring_unmodified_files contributing Loading Loading
README.md +127 −8 Changes for README.md: 127 added lines, 8 removed lines. Original line number Diff line number Diff line Loading @@ -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)** Loading @@ -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} ``` Loading Loading @@ -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')" ``` Loading Loading @@ -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 Loading Loading @@ -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. Loading
docs/index.rst +1 −0 Changes for docs/index.rst: 1 added line, 0 removed lines. Original line number Diff line number Diff line Loading @@ -54,6 +54,7 @@ Contents pyproject_toml editor_integration blackd black-primer version_control_integration ignoring_unmodified_files contributing Loading