X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/9fe788d8704c1d4726b30e41e181c687c02cc1cf..36078bc83f24dcd5f74e021a105429595a3fd63c:/docs/usage_and_configuration/the_basics.md diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md index c7e2d4a..36119f2 100644 --- a/docs/usage_and_configuration/the_basics.md +++ b/docs/usage_and_configuration/the_basics.md @@ -26,57 +26,107 @@ python -m black {source_file_or_directory} ### Command line options -The CLI options of _Black_ can be displayed by expanding the view below or by running -`black --help`. While _Black_ has quite a few knobs these days, it is still opinionated -so style options are deliberately limited and rarely added. +The CLI options of _Black_ can be displayed by running `black --help`. All options are +also covered in more detail below. -
+While _Black_ has quite a few knobs these days, it is still opinionated so style options +are deliberately limited and rarely added. + +Note that all command-line options listed above can also be configured using a +`pyproject.toml` file (more on that below). -CLI reference +#### `-c`, `--code` -```{program-output} black --help +Format the code passed in as a string. +```console +$ black --code "print ( 'hello, world' )" +print("hello, world") ``` -
+#### `-l`, `--line-length` -### Code input alternatives +How many characters per line to allow. The default is 88. -#### Standard Input +See also [the style documentation](labels/line-length). -_Black_ supports formatting code via stdin, with the result being printed to stdout. -Just let _Black_ know with `-` as the path. +#### `-t`, `--target-version` + +Python versions that should be supported by Black's output. You can run `black --help` +and look for the `--target-version` option to see the full list of supported versions. +You should include all versions that your code supports. If you support Python 3.8 +through 3.11, you should write: ```console -$ echo "print ( 'hello, world' )" | black - -print("hello, world") -reformatted - -All done! ✨ 🍰 ✨ -1 file reformatted. +$ black -t py38 -t py39 -t py310 -t py311 ``` -**Tip:** if you need _Black_ to treat stdin input as a file passed directly via the CLI, -use `--stdin-filename`. Useful to make sure _Black_ will respect the `--force-exclude` -option on some editors that rely on using stdin. +In a [configuration file](#configuration-via-a-file), you can write: -#### As a string +```toml +target-version = ["py38", "py39", "py310", "py311"] +``` -You can also pass code as a string using the `-c` / `--code` option. +_Black_ uses this option to decide what grammar to use to parse your code. In addition, +it may use it to decide what style to use. For example, support for a trailing comma +after `*args` in a function call was added in Python 3.5, so _Black_ will add this comma +only if the target versions are all Python 3.5 or higher: ```console -$ black --code "print ( 'hello, world' )" -print("hello, world") +$ black --line-length=10 --target-version=py35 -c 'f(a, *args)' +f( + a, + *args, +) +$ black --line-length=10 --target-version=py34 -c 'f(a, *args)' +f( + a, + *args +) +$ black --line-length=10 --target-version=py34 --target-version=py35 -c 'f(a, *args)' +f( + a, + *args +) ``` -### Writeback and reporting +#### `--pyi` -By default _Black_ reformats the files given and/or found in place. Sometimes you need -_Black_ to just tell you what it _would_ do without actually rewriting the Python files. +Format all input files like typing stubs regardless of file extension. This is useful +when piping source on standard input. -There's two variations to this mode that are independently enabled by their respective -flags. Both variations can be enabled at once. +#### `--ipynb` + +Format all input files like Jupyter Notebooks regardless of file extension. This is +useful when piping source on standard input. + +#### `--python-cell-magics` + +When processing Jupyter Notebooks, add the given magic to the list of known python- +magics. Useful for formatting cells with custom python magics. + +#### `-S, --skip-string-normalization` + +By default, _Black_ uses double quotes for all strings and normalizes string prefixes, +as described in [the style documentation](labels/strings). If this option is given, +strings are left unchanged instead. + +#### `-C, --skip-magic-trailing-comma` -#### Exit code +By default, _Black_ uses existing trailing commas as an indication that short lines +should be left separate, as described in +[the style documentation](labels/magic-trailing-comma). If this option is given, the +magic trailing comma is ignored. + +#### `--preview` + +Enable potentially disruptive style changes that may be added to Black's main +functionality in the next major release. Read more about +[our preview style](labels/preview-style). + +(labels/exit-code)= + +#### `--check` Passing `--check` will make _Black_ exit with: @@ -106,17 +156,17 @@ $ echo $? 123 ``` -#### Diffs +#### `--diff` Passing `--diff` will make _Black_ print out diffs that indicate what changes _Black_ would've made. They are printed to stdout so capturing them is simple. -If you'd like colored diffs, you can enable them with the `--color`. +If you'd like colored diffs, you can enable them with `--color`. ```console $ black test.py --diff ---- test.py 2021-03-08 22:23:40.848954 +0000 -+++ test.py 2021-03-08 22:23:47.126319 +0000 +--- test.py 2021-03-08 22:23:40.848954+00:00 ++++ test.py 2021-03-08 22:23:47.126319+00:00 @@ -1 +1 @@ -print ( 'hello, world' ) +print("hello, world") @@ -125,22 +175,93 @@ All done! ✨ 🍰 ✨ 1 file would be reformatted. ``` -### Output verbosity +#### `--color` / `--no-color` -_Black_ in general tries to produce the right amount of output, balancing between -usefulness and conciseness. By default, _Black_ emits files modified and error messages, -plus a short summary. +Show (or do not show) colored diff. Only applies when `--diff` is given. + +#### `--fast` / `--safe` + +By default, _Black_ performs [an AST safety check](labels/ast-changes) after formatting +your code. The `--fast` flag turns off this check and the `--safe` flag explicitly +enables it. + +#### `--required-version` + +Require a specific version of _Black_ to be running. This is useful for ensuring that +all contributors to your project are using the same version, because different versions +of _Black_ may format code a little differently. This option can be set in a +configuration file for consistent results across environments. ```console -$ black src/ +$ black --version +black, 23.9.1 (compiled: yes) +$ black --required-version 23.9.1 -c "format = 'this'" +format = "this" +$ black --required-version 31.5b2 -c "still = 'beta?!'" +Oh no! 💥 💔 💥 The required version does not match the running version! +``` + +You can also pass just the major version: + +```console +$ black --required-version 22 -c "format = 'this'" +format = "this" +$ black --required-version 31 -c "still = 'beta?!'" +Oh no! 💥 💔 💥 The required version does not match the running version! +``` + +Because of our [stability policy](../the_black_code_style/index.md), this will guarantee +stable formatting, but still allow you to take advantage of improvements that do not +affect formatting. + +#### `--include` + +A regular expression that matches files and directories that should be included on +recursive searches. An empty value means all files are included regardless of the name. +Use forward slashes for directories on all platforms (Windows, too). Exclusions are +calculated first, inclusions later. + +#### `--exclude` + +A regular expression that matches files and directories that should be excluded on +recursive searches. An empty value means no paths are excluded. Use forward slashes for +directories on all platforms (Windows, too). Exclusions are calculated first, inclusions +later. + +#### `--extend-exclude` + +Like `--exclude`, but adds additional files and directories on top of the excluded ones. +Useful if you simply want to add to the default. + +#### `--force-exclude` + +Like `--exclude`, but files and directories matching this regex will be excluded even +when they are passed explicitly as arguments. This is useful when invoking _Black_ +programmatically on changed files, such as in a pre-commit hook or editor plugin. + +#### `--stdin-filename` + +The name of the file when passing it through stdin. Useful to make sure Black will +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 can also be specified via the +`BLACK_NUM_WORKERS` environment variable. + +#### `-q`, `--quiet` + +Passing `-q` / `--quiet` will cause _Black_ to stop emitting all non-critical output. +Error messages will still be emitted (which can silenced by `2>/dev/null`). + +```console +$ black src/ -q error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio -reformatted src/black_primer/lib.py -reformatted src/blackd/__init__.py -reformatted src/black/__init__.py -Oh no! 💥 💔 💥 -3 files reformatted, 2 files left unchanged, 1 file failed to reformat. ``` +#### `-v`, `--verbose` + Passing `-v` / `--verbose` will cause _Black_ to also emit messages about files that were not changed or were ignored due to exclusion patterns. If _Black_ is using a configuration file, a blue message detailing which one it is using will be emitted. @@ -159,35 +280,86 @@ Oh no! 💥 💔 💥 3 files reformatted, 2 files left unchanged, 1 file failed to reformat ``` -Passing `-q` / `--quiet` will cause _Black_ to stop emitting all non-critial output. -Error messages will still be emitted (which can silenced by `2>/dev/null`). +#### `--version` + +You can check the version of _Black_ you have installed using the `--version` flag. ```console -$ black src/ -q -error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio +$ black --version +black, 23.9.1 ``` -### Versions +#### `--config` -You can check the version of _Black_ you have installed using the `--version` flag. +Read configuration options from a configuration file. See +[below](#configuration-via-a-file) for more details on the configuration file. + +#### `-h`, `--help` + +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. +Just let _Black_ know with `-` as the path. ```console -$ black --version -black, version 22.3.0 +$ echo "print ( 'hello, world' )" | black - +print("hello, world") +reformatted - +All done! ✨ 🍰 ✨ +1 file reformatted. ``` -An option to require a specific version to be running is also provided. +**Tip:** if you need _Black_ to treat stdin input as a file passed directly via the CLI, +use `--stdin-filename`. Useful to make sure _Black_ will respect the `--force-exclude` +option on some editors that rely on using stdin. + +You can also pass code as a string using the `-c` / `--code` option. + +### Writeback and reporting + +By default _Black_ reformats the files given and/or found in place. Sometimes you need +_Black_ to just tell you what it _would_ do without actually rewriting the Python files. + +There's two variations to this mode that are independently enabled by their respective +flags: + +- `--check` (exit with code 1 if any file would be reformatted) +- `--diff` (print a diff instead of reformatting files) + +Both variations can be enabled at once. + +### Output verbosity + +_Black_ in general tries to produce the right amount of output, balancing between +usefulness and conciseness. By default, _Black_ emits files modified and error messages, +plus a short summary. ```console -$ black --required-version 21.9b0 -c "format = 'this'" -format = "this" -$ black --required-version 31.5b2 -c "still = 'beta?!'" -Oh no! 💥 💔 💥 The required version does not match the running version! +$ black src/ +error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio +reformatted src/black_primer/lib.py +reformatted src/blackd/__init__.py +reformatted src/black/__init__.py +Oh no! 💥 💔 💥 +3 files reformatted, 2 files left unchanged, 1 file failed to reformat. ``` -This is useful for example when running _Black_ in multiple environments that haven't -necessarily installed the correct version. This option can be set in a configuration -file for consistent results across environments. +The `--quiet` and `--verbose` flags control output verbosity. ## Configuration via a file @@ -204,9 +376,10 @@ code in compliance with many other _Black_ formatted projects. [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://python-poetry.org/) or -[Flit](https://flit.readthedocs.io/en/latest/) it can fully replace the need for -`setup.py` and `setup.cfg` files. +of tools like [Poetry](https://python-poetry.org/), +[Flit](https://flit.readthedocs.io/en/latest/), or +[Hatch](https://hatch.pypa.io/latest/) it can fully replace the need for `setup.py` and +`setup.cfg` files. ### Where _Black_ looks for the file @@ -265,7 +438,7 @@ extend-exclude = ''' # in the root of the project. ( ^/foo.py # exclude a file named foo.py in the root of the project - | *_pb2.py # exclude autogenerated Protocol Buffer files anywhere in the project + | .*_pb2.py # exclude autogenerated Protocol Buffer files anywhere in the project ) ''' ``` @@ -284,9 +457,6 @@ file hierarchy. ## Next steps -You've probably noted that not all of the options you can pass to _Black_ have been -covered. Don't worry, the rest will be covered in a later section. - A good next step would be configuring auto-discovery so `black .` is all you need instead of laborously listing every file or directory. You can get started by heading over to [File collection and discovery](./file_collection_and_discovery.md).