X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/1b189f6cdeca7b1f9669e0152c92875dff7b761a..94ebcb50851e40cba88c6ad2c14f9dfe45e08921:/README.md diff --git a/README.md b/README.md index 12af03f..533a1f8 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,10 @@

Build Status -Documentation Status +Documentation Status Coverage Status -License: MIT -PyPI +License: MIT +PyPI Code style: black

@@ -29,13 +29,13 @@ possible. --- *Contents:* **[Installation and usage](#installation-and-usage)** | -**[The *Black* code style](#the-black-code-style)** | +**[Code style](#the-black-code-style)** | +**[pyproject.toml](#pyprojecttoml)** | **[Editor integration](#editor-integration)** | **[Version control integration](#version-control-integration)** | **[Ignoring unmodified files](#ignoring-unmodified-files)** | **[Testimonials](#testimonials)** | **[Show your style](#show-your-style)** | -**[License](#license)** | **[Contributing](#contributing-to-black)** | **[Change Log](#change-log)** | **[Authors](#authors)** @@ -60,7 +60,7 @@ black {source_file_or_directory} ### Command line options -Black doesn't provide many options. You can list them by running +*Black* doesn't provide many options. You can list them by running `black --help`: ```text @@ -68,6 +68,15 @@ black [OPTIONS] [SRC]... Options: -l, --line-length INTEGER Where to wrap around. [default: 88] + --py36 Allow using Python 3.6-only syntax on all input + files. This will put trailing commas in function + signatures and calls also after *args and + **kwargs. [default: per-file auto-detection] + --pyi Format all input files like typing stubs + regardless of file extension (useful when piping + source on standard input). + -S, --skip-string-normalization + Don't normalize string quotes or prefixes. --check Don't write the files back, just return the status. Return code 0 means nothing would change. Return code 1 means some files would be @@ -77,19 +86,24 @@ Options: for each file on stdout. --fast / --safe If --fast given, skip temporary sanity checks. [default: --safe] + --include TEXT A regular expression that matches files and + directories that should be included on + recursive searches. On Windows, use forward + slashes for directories. [default: \.pyi?$] + --exclude TEXT A regular expression that matches files and + directories that should be excluded on + recursive searches. On Windows, use forward + slashes for directories. [default: + build/|buck-out/|dist/|_build/|\.git/|\.hg/| + \.mypy_cache/|\.tox/|\.venv/] -q, --quiet Don't emit non-error messages to stderr. Errors are still emitted, silence those with 2>/dev/null. - --pyi Consider all input files typing stubs regardless - of file extension (useful when piping source on - standard input). - --py36 Allow using Python 3.6-only syntax on all input - files. This will put trailing commas in function - signatures and calls also after *args and - **kwargs. [default: per-file auto-detection] - -S, --skip-string-normalization - Don't normalize string quotes or prefixes. + -v, --verbose Also emit messages to stderr about files + that were not changed or were ignored due to + --exclude=. --version Show the version and exit. + --config PATH Read configuration from PATH. --help Show this message and exit. ``` @@ -474,6 +488,98 @@ a future version of the formatter: * use `float` instead of `Union[int, float]`. +## pyproject.toml + +*Black* is able to read project-specific default values for its +command line options from a `pyproject.toml` file. This is +especially useful for specifying custom `--include` and `--exclude` +patterns for your project. + +**Pro-tip**: If you're asking yourself "Do I need to configure anything?" +the answer is "No". *Black* is all about sensible defaults. + + +### What on Earth is a `pyproject.toml` file? + +[PEP 518](https://www.python.org/dev/peps/pep-0518/) defines +`pyproject.toml` as a configuration file to store build system +requirements for Python projects. With the help of tools +like [Poetry](https://poetry.eustace.io/) or +[Flit](https://flit.readthedocs.io/en/latest/) it can fully replace the +need for `setup.py` and `setup.cfg` files. + + +### Where *Black* looks for the file + +By default *Black* looks for `pyproject.toml` starting from the common +base directory of all files and directories passed on the command line. +If it's not there, it looks in parent directories. It stops looking +when it finds the file, or a `.git` directory, or a `.hg` directory, +or the root of the file system, whichever comes first. + +If you're formatting standard input, *Black* will look for configuration +starting from the current working directory. + +You can also explicitly specify the path to a particular file that you +want with `--config`. In this situation *Black* will not look for any +other file. + +If you're running with `--verbose`, you will see a blue message if +a file was found and used. + + +### Configuration format + +As the file extension suggests, `pyproject.toml` is a [TOML](https://github.com/toml-lang/toml) file. It contains separate +sections for different tools. *Black* is using the `[tool.black]` +section. The option keys are the same as long names of options on +the command line. + +Note that you have to use single-quoted strings in TOML for regular +expressions. It's the equivalent of r-strings in Python. Multiline +strings are treated as verbose regular expressions by Black. Use `[ ]` +to denote a significant space character. + +
+Example `pyproject.toml` + +```toml +[tool.black] +line-length = 88 +py36 = true +include = '\.pyi?$' +exclude = ''' +/( + \.git + | \.hg + | \.mypy_cache + | \.tox + | \.venv + | _build + | buck-out + | build + | dist + + # The following are specific to Black, you probably don't want those. + | blib2to3 + | tests/data +)/ +''' +``` + +
+ +### Lookup hierarchy + +Command-line options have defaults that you can see in `--help`. +A `pyproject.toml` can override those defaults. Finally, options +provided by the user on the command line override both. + +*Black* will only ever use one `pyproject.toml` file during an entire +run. It doesn't look for multiple files, and doesn't compose +configuration from different levels of the file hierarchy. + + ## Editor integration ### Emacs @@ -529,6 +635,7 @@ Commands and shortcuts: Configuration: * `g:black_fast` (defaults to `0`) * `g:black_linelength` (defaults to `88`) +* `g:black_skip_string_normalization` (defaults to `0`) * `g:black_virtualenv` (defaults to `~/.vim/black`) To install with [vim-plug](https://github.com/junegunn/vim-plug): @@ -576,7 +683,9 @@ to do this. ### Visual Studio Code -Use [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode). +Use the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) +([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)) +or [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode). ### SublimeText 3 @@ -597,7 +706,7 @@ require external contributions. Patches welcome! ✨ 🍰 ✨ Any tool that can pipe code through *Black* using its stdio mode (just -[use `-` as the file name](http://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2)). +[use `-` as the file name](https://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2)). The formatted code will be returned on stdout (unless `--check` was passed). *Black* will still emit messages on stderr but that shouldn't affect your use case. @@ -616,23 +725,25 @@ repos: rev: stable hooks: - id: black - args: [--line-length=88, --safe] - python_version: python3.6 + language_version: python3.6 ``` Then run `pre-commit install` and you're ready to go. -`args` in the above config is optional but shows you how you can change -the line length if you really need to. If you're already using Python -3.7, switch the `python_version` accordingly. Finally, `stable` is a tag -that is pinned to the latest release on PyPI. If you'd rather run on -master, this is also an option. +Avoid using `args` in the hook. Instead, store necessary configuration +in `pyproject.toml` so that editors and command-line usage of Black all +behave consistently for your project. See *Black*'s own `pyproject.toml` +for an example. + +If you're already using Python 3.7, switch the `language_version` +accordingly. Finally, `stable` is a tag that is pinned to the latest +release on PyPI. If you'd rather run on master, this is also an option. ## Ignoring unmodified files *Black* remembers files it has already formatted, unless the `--diff` flag is used or code is passed via standard input. This information is stored per-user. The exact -location of the file depends on the black version and the system on which black +location of the file depends on the *Black* version and the system on which *Black* is run. The file is non-portable. The standard location on common operating systems is: @@ -645,7 +756,7 @@ is: **Dusty Phillips**, [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips): -> Black is opinionated so you don't have to be. +> *Black* is opinionated so you don't have to be. **Hynek Schlawack**, [creator of `attrs`](http://www.attrs.org/), core developer of Twisted and CPython: @@ -678,7 +789,7 @@ Looks like this: [![Code style: black](https://img.shields.io/badge/code%20style MIT -## Contributing to Black +## Contributing to *Black* In terms of inspiration, *Black* is about as configurable as *gofmt*. This is deliberate. @@ -696,13 +807,53 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). ## Change Log +### 18.6b3 + +* fixed improper formatting of f-strings with quotes inside interpolated + expressions (#322) + +### 18.6b2 + +* added `--config` (#65) + +* added `-h` equivalent to `--help` (#316) + +* fixed improper unmodified file caching when `-S` was used + +* fixed extra space in string unpacking (#305) + +* fixed formatting of empty triple quoted strings (#313) + +* fixed unnecessary slowdown in comment placement calculation on lines without + comments + + +### 18.6b1 + +* hotfix: don't output human-facing information on stdout (#299) + +* hotfix: don't output cake emoji on non-zero return code (#300) + + ### 18.6b0 +* added `--include` and `--exclude` (#270) + * added `--skip-string-normalization` (#118) +* added `--verbose` (#283) + +* the header output in `--diff` now actually conforms to the unified diff spec + +* fixed long trivial assignments being wrapped in unnecessary parentheses (#273) + +* fixed unnecessary parentheses when a line contained multiline strings (#232) + * fixed stdin handling not working correctly if an old version of Click was used (#276) +* *Black* now preserves line endings when formatting a file in place (#258) + ### 18.5b1 @@ -808,10 +959,10 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). * generalized star expression handling, including double stars; this fixes multiplication making expressions "unsafe" for trailing commas (#132) -* Black no longer enforces putting empty lines behind control flow statements +* *Black* no longer enforces putting empty lines behind control flow statements (#90) -* Black now splits imports like "Mode 3 + trailing comma" of isort (#127) +* *Black* now splits imports like "Mode 3 + trailing comma" of isort (#127) * fixed comment indentation when a standalone comment closes a block (#16, #32) @@ -864,16 +1015,16 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). (#75) * fixed handling of standalone comments within nested bracketed - expressions; Black will no longer produce super long lines or put all + expressions; *Black* will no longer produce super long lines or put all standalone comments at the end of the expression (#22) * fixed 18.3a4 regression: don't crash and burn on empty lines with trailing whitespace (#80) * fixed 18.3a4 regression: `# yapf: disable` usage as trailing comment - would cause Black to not emit the rest of the file (#95) + would cause *Black* to not emit the rest of the file (#95) -* when CTRL+C is pressed while formatting many files, Black no longer +* when CTRL+C is pressed while formatting many files, *Black* no longer freaks out with a flurry of asyncio-related exceptions * only allow up to two empty lines on module level and only single empty @@ -995,21 +1146,7 @@ Multiple contributions by: * [Luka Sterbic](mailto:luka.sterbic@gmail.com) * [Miguel Gaiowski](mailto:miggaiowski@gmail.com) * [Osaetin Daniel](mailto:osaetindaniel@gmail.com) +* [Peter Bengtsson](mailto:mail@peterbe.com) * [Stavros Korokithakis](mailto:hi@stavros.io) * [Sunil Kapil](mailto:snlkapil@gmail.com) * [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com) - ---- - -*Contents:* -**[Installation and Usage](#installation-and-usage)** | -**[The *Black* code style](#the-black-code-style)** | -**[Editor integration](#editor-integration)** | -**[Version control integration](#version-control-integration)** | -**[Ignoring unmodified files](#ignoring-unmodified-files)** | -**[Testimonials](#testimonials)** | -**[Show your style](#show-your-style)** | -**[License](#license)** | -**[Contributing](#contributing-to-black)** | -**[Change Log](#change-log)** | -**[Authors](#authors)**