Merge branch 'master' of https://github.com/psf/black

CONTRIBUTING.md

@@ -34,14 +34,40 @@ If you haven't used `pipenv` before but are comfortable with virtualenvs, just r
 `pip install pipenv` in the virtualenv you're already using and invoke the command above
 from the cloned _Black_ repo. It will do the correct thing.
 
-Before submitting pull requests, run lints and tests with:
+Non pipenv install works too:
 
 ```console
+$ pip install -r test_requirements
+$ pip install -e .[d]
+```
+
+Before submitting pull requests, run lints and tests with the following commands from
+the root of the black repo:
+
+```console
+# Linting
 $ pre-commit run -a
-$ python -m unittest
+
+# Unit tests
+$ tox -e py
+
+# Optional Fuzz testing
+$ tox -e fuzz
+
+# Optional CI run to test your changes on many popular python projects
 $ black-primer [-k -w /tmp/black_test_repos]
 ```
 
+### Docs Testing
+
+If you make changes to docs, you can test they still build locally too.
+
+```console
+$ pip install -r docs/requirements.txt
+$ pip install [-e] .[d]
+$ sphinx-build -a -b html -W docs/ docs/_build/
+```
+
 ## black-primer
 
 `black-primer` is used by CI to pull down well-known _Black_ formatted projects and see
@@ -52,7 +78,7 @@ your PR. You may need to change
 configuration for it to pass.
 
 For more `black-primer` information visit the
-[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md#black-primer).
+[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md).
 
 ## Hygiene
 

README.md

@@ -97,6 +97,10 @@ Options:
 
   -S, --skip-string-normalization
                                   Don't normalize string quotes or prefixes.
+  -C, --skip-magic-trailing-comma
+                                  Don't use trailing commas as a reason to
+                                  split lines.
+
   --check                         Don't write the files back, just return the
                                   status.  Return code 0 means nothing would
                                   change.  Return code 1 means some files
@@ -127,18 +131,19 @@ Options:
                                   paths are excluded. Use forward slashes for
                                   directories on all platforms (Windows, too).
                                   Exclusions are calculated first, inclusions
-                                  later.  [default: /(\.eggs|\.git|\.hg|\.mypy
-                                  _cache|\.nox|\.tox|\.venv|\.svn|_build|buck-
-                                  out|build|dist)/]
+                                  later.  [default: /(\.direnv|\.eggs|\.git|\.
+                                  hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_bu
+                                  ild|buck-out|build|dist)/]
 
   --force-exclude TEXT            Like --exclude, but files and directories
                                   matching this regex will be excluded even
-                                  when they are passed explicitly as arguments.
+                                  when they are passed explicitly as
+                                  arguments.
 
   --stdin-filename TEXT           The name of the file when passing it through
-                                  stdin. Useful to make sure Black will respect
-                                  --force-exclude option on some editors that
-                                  rely on using stdin.
+                                  stdin. Useful to make sure Black will
+                                  respect --force-exclude option on some
+                                  editors that rely on using stdin.
 
   -q, --quiet                     Don't emit non-error messages to stderr.
                                   Errors are still emitted; silence those with
@@ -411,8 +416,16 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
       - uses: psf/black@stable
+        with:
+          black_args: ". --check"
 ```
 
+### Inputs
+
+#### `black_args`
+
+**optional**: Black input arguments. Defaults to `. --check --diff`.
+
 ## Ignoring unmodified files
 
 _Black_ remembers files it has already formatted, unless the `--diff` flag is used or

action.yml

@@ -1,6 +1,11 @@
 name: "Black"
 description: "The uncompromising Python code formatter."
 author: "Łukasz Langa and contributors to Black"
+inputs:
+  black_args:
+    description: "Black input arguments."
+    required: false
+    default: ""
 branding:
   color: "black"
   icon: "check-circle"

action/entrypoint.sh

@@ -1,10 +1,17 @@
-#!/bin/sh
+#!/bin/bash
 set -e
 
-if [ $# -eq 0 ]; then
-    # Default (if no args provided).
-    sh -c "black . --check --diff"
+# If no arguments are given use current working directory
+black_args=(".")
+if [ "$#" -eq 0 ] && [ "${INPUT_BLACK_ARGS}" != "" ]; then
+  black_args+=(${INPUT_BLACK_ARGS})
+elif [ "$#" -ne 0 ] && [ "${INPUT_BLACK_ARGS}" != "" ]; then
+  black_args+=($* ${INPUT_BLACK_ARGS})
+elif [ "$#" -ne 0 ] && [ "${INPUT_BLACK_ARGS}" == "" ]; then
+  black_args+=($*)
 else
-    # Custom args.
-    sh -c "black $*"
+  # Default (if no args provided).
+  black_args+=("--check" "--diff")
 fi
+
+sh -c "black . ${black_args[*]}"

docs/blackd.md

@@ -54,6 +54,9 @@ The headers controlling how source code is formatted are:
 - `X-Skip-String-Normalization`: corresponds to the `--skip-string-normalization`
   command line flag. If present and its value is not the empty string, no string
   normalization will be performed.
+- `X-Skip-Magic-Trailing-Comma`: corresponds to the `--skip-magic-trailing-comma`
+  command line flag. If present and its value is not the empty string, trailing commas
+  will not be used as a reason to split lines.
 - `X-Fast-Or-Safe`: if set to `fast`, `blackd` will act as _Black_ does when passed the
   `--fast` command line flag.
 - `X-Python-Variant`: if set to `pyi`, `blackd` will act as _Black_ does when passed the

docs/change_log.md

@@ -23,8 +23,15 @@
 
 - Added support for PEP 614 relaxed decorator syntax on python 3.9 (#1711)
 
-- Added `--stdin-filename` argument to allow stdin to respect `--force-exclude` rules.
-  Works very alike to flake8's `--stdin-display-name` (#1780)
+- Added parsing support for unparenthesized tuples and yield expressions in annotated
+  assignments (#1835)
+
+- use lowercase hex strings (#1692)
+
+#### _Packaging_
+
+- Self-contained native _Black_ binaries are now provided for releases via GitHub
+  Releases (#1743)
 
 ### 20.8b1
 

docs/compatible_configs.md

@@ -221,7 +221,7 @@ max-line-length = 88
 ### Why those options above?
 
 When _Black_ is folding very long expressions, the closing brackets will
-[be dedented](https://github.com/psf/black#how-black-wraps-lines).
+[be dedented](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#how-black-wraps-lines).
 
 ```py3
 ImportantClass.important_method(

docs/compatible_configs/isort/pyproject.toml

@@ -1,2 +1,2 @@
 [tool.isort]
-profile = black
+profile = 'black'

docs/contributing_to_black.md

@@ -36,14 +36,40 @@ If you haven't used `pipenv` before but are comfortable with virtualenvs, just r
 `pip install pipenv` in the virtualenv you're already using and invoke the command above
 from the cloned _Black_ repo. It will do the correct thing.
 
-Before submitting pull requests, run lints and tests with:
+Non pipenv install works too:
 
 ```console
+$ pip install -r test_requirements
+$ pip install -e .[d]
+```
+
+Before submitting pull requests, run lints and tests with the following commands from
+the root of the black repo:
+
+```console
+# Linting
 $ pre-commit run -a
-$ python -m unittest
+
+# Unit tests
+$ tox -e py
+
+# Optional Fuzz testing
+$ tox -e fuzz
+
+# Optional CI run to test your changes on many popular python projects
 $ black-primer [-k -w /tmp/black_test_repos]
 ```
 
+### Docs Testing
+
+If you make changes to docs, you can test they still build locally too.
+
+```console
+$ pip install -r docs/requirements.txt
+$ pip install [-e] .[d]
+$ sphinx-build -a -b html -W docs/ docs/_build/
+```
+
 ## black-primer
 
 `black-primer` is used by CI to pull down well-known _Black_ formatted projects and see
@@ -54,7 +80,7 @@ your PR. You may need to change
 configuration for it to pass.
 
 For more `black-primer` information visit the
-[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md#).
+[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md).
 
 ## Hygiene
 

docs/github_actions.md

@@ -15,7 +15,13 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
-      - uses: psf/black@stable # the default is equivalent to `black . --diff --check`.
-        with: # (optional - override the default parameters).
-          args: ". --diff --check"
+      - uses: psf/black@stable
+        with:
+          black_args: ". --check"
 ```
+
+## Inputs
+
+### `black_args`
+
+**optional**: Black input arguments. Defaults to `. --check --diff`.

docs/installation_and_usage.md

@@ -52,6 +52,10 @@ Options:
 
   -S, --skip-string-normalization
                                   Don't normalize string quotes or prefixes.
+  -C, --skip-magic-trailing-comma
+                                  Don't use trailing commas as a reason to
+                                  split lines.
+
   --check                         Don't write the files back, just return the
                                   status.  Return code 0 means nothing would
                                   change.  Return code 1 means some files
@@ -82,13 +86,24 @@ Options:
                                   paths are excluded. Use forward slashes for
                                   directories on all platforms (Windows, too).
                                   Exclusions are calculated first, inclusions
-                                  later.  [default: /(\.eggs|\.git|\.hg|\.mypy
-                                  _cache|\.nox|\.tox|\.venv|\.svn|_build|buck-
-                                  out|build|dist)/]
+                                  later.  [default: /(\.direnv|\.eggs|\.git|\.
+                                  hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_bu
+                                  ild|buck-out|build|dist)/]
 
   --force-exclude TEXT            Like --exclude, but files and directories
                                   matching this regex will be excluded even
-                                  when they are passed explicitly as arguments.
+                                  when they are passed explicitly as
+                                  arguments.
+
+  --stdin-filename TEXT           The name of the file when passing it through
+                                  stdin. Useful to make sure Black will
+                                  respect --force-exclude option on some
+                                  editors that rely on using stdin.
+
+  --stdin-filename TEXT           The name of the file when passing it through
+                                  stdin. Useful to make sure Black will respect
+                                  --force-exclude option on some editors that
+                                  rely on using stdin.
 
   -q, --quiet                     Don't emit non-error messages to stderr.
                                   Errors are still emitted; silence those with
@@ -119,7 +134,7 @@ about _Black_'s changes or will overwrite _Black_'s changes. A good example of t
 should be configured to neither warn about nor overwrite _Black_'s changes.
 
 Actual details on _Black_ compatible configurations for various tools can be found in
-[compatible_configs](https://github.com/psf/black/blob/master/docs/compatible_configs.md#).
+[compatible_configs](https://github.com/psf/black/blob/master/docs/compatible_configs.md#black-compatible-configurations).
 
 ## Migrating your code style without ruining git blame
 

docs/the_black_code_style.md

@@ -438,6 +438,9 @@ into one item per line.
 How do you make it stop? Just delete that trailing comma and _Black_ will collapse your
 collection into one line if it fits.
 
+If you must, you can recover the behaviour of early versions of Black with the option
+`--skip-magic-trailing-comma` / `-C`.
+
 ### r"strings" and R"strings"
 
 _Black_ normalizes string quotes as well as string prefixes, making them lowercase. One

docs/version_control_integration.md

@@ -23,11 +23,6 @@ for your project. See _Black_'s own
 [pyproject.toml](https://github.com/psf/black/blob/master/pyproject.toml) for an
 example.
 
-When using the `--diff` flag with `pre-commit`, you must also use the `--check` flag.
-When you want to run _Black_ only on specific files in pre-commit, either use
-pre-commit's own `files` and `exclude` or, when using _Black_'s `--include`, set
-`--force-exclude` to the negated regex of `--include`.
-
 If you're already using Python 3.7, switch the `language_version` accordingly. Finally,
 `stable` is a branch that tracks the latest release on PyPI. If you'd rather run on
 master, this is also an option.

fuzz.py

@@ -56,4 +56,17 @@ def test_idempotent_any_syntatically_valid_python(
 
 
 if __name__ == "__main__":
+    # Run tests, including shrinking and reporting any known failures.
     test_idempotent_any_syntatically_valid_python()
+
+    # If Atheris is available, run coverage-guided fuzzing.
+    # (if you want only bounded fuzzing, just use `pytest fuzz.py`)
+    try:
+        import sys
+        import atheris
+    except ImportError:
+        pass
+    else:
+        test = test_idempotent_any_syntatically_valid_python
+        atheris.Setup(sys.argv, test.hypothesis.fuzz_one_input)
+        atheris.Fuzz()