Allow specifying `--workers` via environment variable (#3743)

diff --git a/CHANGES.md b/CHANGES.md
index 460f9c95114cbceaa9d2e58a9c8708f92d7caa32..9717867df4e146844fe48499ee4cd8e9c3ace44a 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -25,6 +25,8 @@
 
 <!-- Changes to how Black can be configured -->
 
+- The `--workers` argument to Black can now be specified via the `BLACK_NUM_WORKERS`
+  environment variable (#3743)
 - `.pytest_cache`, `.ruff_cache` and `.vscode` are now excluded by default (#3691)
 - Fix black not honouring `pyproject.toml` settings when running `--stdin-filename` and
   the `pyproject.toml` found isn't in the current working directory (#3719)

diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index 6f3a3cff30c58f6ccbdb6c3df29a61ef20e34256..2a46148721019b076c0ea6bc1cfb581bc5d50ebc 100644 (file)
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -246,7 +246,8 @@ respect the `--force-exclude` option on some editors that rely on using stdin.
 #### `-W`, `--workers`
 
 When _Black_ formats multiple files, it may use a process pool to speed up formatting.
-This option controls the number of parallel workers.
+This option controls the number of parallel workers. This can also be specified via the
+`BLACK_NUM_WORKERS` environment variable.
 
 #### `-q`, `--quiet`
 
@@ -296,6 +297,19 @@ Read configuration options from a configuration file. See
 
 Show available command-line options and exit.
 
+### Environment variable options
+
+_Black_ supports the following configuration via environment variables.
+
+#### `BLACK_CACHE_DIR`
+
+The directory where _Black_ should store its cache.
+
+#### `BLACK_NUM_WORKERS`
+
+The number of parallel workers _Black_ should use. The command line option `-W` /
+`--workers` takes precedence over this environment variable.
+
 ### Code input alternatives
 
 _Black_ supports formatting code via stdin, with the result being printed to stdout.

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 60a339cdd12ec9d5617537556c87bdb223e03c57..3451c86b50893859be638e1a608a58e1ebf15881 100644 (file)
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -376,7 +376,10 @@ def validate_regex(
     "--workers",
     type=click.IntRange(min=1),
     default=None,
-    help="Number of parallel workers [default: number of CPUs in the system]",
+    help=(
+        "Number of parallel workers [default: BLACK_NUM_WORKERS environment variable "
+        "or number of CPUs in the system]"
+    ),
 )
 @click.option(
     "-q",

diff --git a/src/black/concurrency.py b/src/black/concurrency.py
index 1598f51e43f5a08b4ed428ebb15413798a0e3991..893eba6675a738a7b1eab2471075caa87130430a 100644 (file)
--- a/src/black/concurrency.py
+++ b/src/black/concurrency.py
@@ -80,7 +80,8 @@ def reformat_many(
 
     executor: Executor
     if workers is None:
-        workers = os.cpu_count() or 1
+        workers = int(os.environ.get("BLACK_NUM_WORKERS", 0))
+        workers = workers or os.cpu_count() or 1
     if sys.platform == "win32":
         # Work around https://bugs.python.org/issue26903
         workers = min(workers, 60)