X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/81a093e82a860c4b7e559532a847ccd967e6e456..6a105e019fcaa10cc0b6fb59edea4a4018eac97e:/README.md diff --git a/README.md b/README.md index 4b65fb7..89ef427 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ License: MIT PyPI Downloads +conda-forge Code style: black

@@ -85,7 +86,7 @@ Options: -l, --line-length INTEGER How many characters per line to allow. [default: 88] - -t, --target-version [py27|py33|py34|py35|py36|py37|py38] + -t, --target-version [py27|py33|py34|py35|py36|py37|py38|py39] Python versions that should be supported by Black's output. [default: per-file auto- detection] @@ -96,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 @@ -126,13 +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. -q, --quiet Don't emit non-error messages to stderr. Errors are still emitted; silence those with @@ -143,7 +154,7 @@ Options: --exclude=. --version Show the version and exit. - --config FILE Read configuration from PATH. + --config FILE Read configuration from FILE path. -h, --help Show this message and exit. ``` @@ -163,7 +174,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 @@ -211,12 +222,13 @@ know!) ### NOTE: This is a beta product -_Black_ is already [successfully used](#used-by) by many projects, small and big. It -also sports a decent test suite. However, it is still very new. Things will probably be -wonky for a while. This is made explicit by the "Beta" trove classifier, as well as by -the "b" in the version number. What this means for you is that **until the formatter -becomes stable, you should expect some formatting to change in the future**. That being -said, no drastic stylistic changes are planned, mostly responses to bug reports. +_Black_ is already [successfully used](https://github.com/psf/black#used-by) by many +projects, small and big. It also sports a decent test suite. However, it is still very +new. Things will probably be wonky for a while. This is made explicit by the "Beta" +trove classifier, as well as by the "b" in the version number. What this means for you +is that **until the formatter becomes stable, you should expect some formatting to +change in the future**. That being said, no drastic stylistic changes are planned, +mostly responses to bug reports. Also, as a temporary safety measure, _Black_ will check that the reformatted code still produces a valid AST that is equivalent to the original. This slows it down. If you're @@ -227,8 +239,9 @@ feeling confident, use `--fast`. _Black_ is a PEP 8 compliant opinionated formatter. _Black_ reformats entire files in place. It is not configurable. It doesn't take previous formatting into account. Your main option of configuring _Black_ is that it doesn't reformat blocks that start with -`# fmt: off` and end with `# fmt: on`. `# fmt: on/off` have to be on the same level of -indentation. To learn more about _Black_'s opinions, to go +`# fmt: off` and end with `# fmt: on`, or lines that ends with `# fmt: skip`. Pay +attention that `# fmt: on/off` have to be on the same level of indentation. To learn +more about _Black_'s opinions, to go [the_black_code_style](https://github.com/psf/black/blob/master/docs/the_black_code_style.md). Please refer to this document before submitting an issue. What seems like a bug might be @@ -293,7 +306,7 @@ the equivalent of r-strings in Python. Multiline strings are treated as verbose expressions by Black. Use `[ ]` to denote a significant space character.
-Example `pyproject.toml` +Example pyproject.toml ```toml [tool.black] @@ -301,9 +314,10 @@ line-length = 88 target-version = ['py37'] include = '\.pyi?$' exclude = ''' - -( - /( +# A regex preceded with ^/ will apply only to files and directories +# in the root of the project. +^/( + ( \.eggs # exclude a few common directories in the | \.git # root of the project | \.hg @@ -354,8 +368,8 @@ rolling. ## 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. +`black-primer` is a tool built for CI (and humans) to have _Black_ `--check` a number of +(configured in `primer.json`) Git accessible projects in parallel. [black_primer](https://github.com/psf/black/blob/master/docs/black_primer.md) has more information regarding its usage and configuration. @@ -370,10 +384,10 @@ Use [pre-commit](https://pre-commit.com/). Once you ```yaml repos: - repo: https://github.com/psf/black - rev: stable + rev: 20.8b1 # Replace by any tag/version: https://github.com/psf/black/tags hooks: - id: black - language_version: python3.6 + language_version: python3 # Should be a command that runs python3.6+ ``` Then run `pre-commit install` and you're ready to go. @@ -404,8 +418,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 @@ -433,9 +455,9 @@ then write the above files to `.cache/black//`. 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, Bandersnatch, Pipenv, virtualenv), pandas, Pillow, -every Datadog Agent Integration, Home Assistant. +every Datadog Agent Integration, Home Assistant, Zulip. -The following organizations use _Black_: Facebook, Dropbox. +The following organizations use _Black_: Facebook, Dropbox, Mozilla, Quora. Are we missing anyone? Let us know. @@ -464,7 +486,7 @@ Twisted and CPython: Use the badge in your project's README.md: -```markdown +```md [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) ``` @@ -548,6 +570,7 @@ Multiple contributions by: - [Christian Clauss](mailto:cclauss@bluewin.ch) - [Christian Heimes](mailto:christian@python.org) - [Chuck Wooters](mailto:chuck.wooters@microsoft.com) +- [Chris Rose](mailto:offline@offby1.net) - Codey Oxley - [Cong](mailto:congusbongus@gmail.com) - [Cooper Ry Lees](mailto:me@cooperlees.com) @@ -571,6 +594,7 @@ Multiple contributions by: - [Gregory P. Smith](mailto:greg@krypto.org) - Gustavo Camargo - hauntsaninja +- [Hadi Alqattan](mailto:alqattanhadizaki@gmail.com) - [Heaford](mailto:dan@heaford.com) - [Hugo Barrera](mailto::hugo@barrera.io) - Hugo van Kemenade @@ -624,7 +648,7 @@ Multiple contributions by: - [Miroslav Shubernetskiy](mailto:miroslav@miki725.com) - MomIsBestFriend - [Nathan Goldbaum](mailto:ngoldbau@illinois.edu) -- [Nathan Hunt](mailtoneighthan.hunt@gmail.com) +- [Nathan Hunt](mailto:neighthan.hunt@gmail.com) - [Neraste](mailto:neraste.herr10@gmail.com) - [Nikolaus Waxweiler](mailto:madigens@gmail.com) - [Ofek Lev](mailto:ofekmeister@gmail.com) @@ -634,6 +658,7 @@ Multiple contributions by: - [Paul Ganssle](mailto:p.ganssle@gmail.com) - [Paul Meinhardt](mailto:mnhrdt@gmail.com) - [Peter Bengtsson](mailto:mail@peterbe.com) +- [Peter Grayson](mailto:pete@jpgrayson.net) - [Peter Stensmyr](mailto:peter.stensmyr@gmail.com) - pmacosta - [Quentin Pradet](mailto:quentin@pradet.me) @@ -683,3 +708,4 @@ Multiple contributions by: - Yazdan - [Yngve Høiseth](mailto:yngve@hoiseth.net) - [Yurii Karabas](mailto:1998uriyyo@gmail.com) +- [Zac Hatfield-Dodds](mailto:zac@zhd.dev)