X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/47480ca33143b250cb33ba501f201838269173ce..43b53a034c9e3ada9295bf7f93be473b66b74f75:/.vim/bundle/black/docs/usage_and_configuration/the_basics.md diff --git a/.vim/bundle/black/docs/usage_and_configuration/the_basics.md b/.vim/bundle/black/docs/usage_and_configuration/the_basics.md deleted file mode 100644 index 5b132a95..00000000 --- a/.vim/bundle/black/docs/usage_and_configuration/the_basics.md +++ /dev/null @@ -1,466 +0,0 @@ -# The basics - -Foundational knowledge on using and configuring Black. - -_Black_ is a well-behaved Unix-style command-line tool: - -- it does nothing if it finds no sources to format; -- it will read from standard input and write to standard output if `-` is used as the - filename; -- it only outputs messages to users on standard error; -- exits with code 0 unless an internal error occurred or a CLI option prompted it. - -## Usage - -To get started right away with sensible defaults: - -```sh -black {source_file_or_directory} -``` - -You can run _Black_ as a package if running it as a script doesn't work: - -```sh -python -m black {source_file_or_directory} -``` - -### Command line options - -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). - -#### `-c`, `--code` - -Format the code passed in as a string. - -```console -$ black --code "print ( 'hello, world' )" -print("hello, world") -``` - -#### `-l`, `--line-length` - -How many characters per line to allow. The default is 88. - -See also [the style documentation](labels/line-length). - -#### `-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 -$ black -t py38 -t py39 -t py310 -t py311 -``` - -In a [configuration file](#configuration-via-a-file), you can write: - -```toml -target-version = ["py38", "py39", "py310", "py311"] -``` - -_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 --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 -) -``` - -#### `--pyi` - -Format all input files like typing stubs regardless of file extension. This is useful -when piping source on standard input. - -#### `--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` - -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: - -- code 0 if nothing would change; -- code 1 if some files would be reformatted; or -- code 123 if there was an internal error - -```console -$ black test.py --check -All done! ✨ 🍰 ✨ -1 file would be left unchanged. -$ echo $? -0 - -$ black test.py --check -would reformat test.py -Oh no! 💥 💔 💥 -1 file would be reformatted. -$ echo $? -1 - -$ black test.py --check -error: cannot format test.py: INTERNAL ERROR: Black produced code that is not equivalent to the source. Please report a bug on https://github.com/psf/black/issues. This diff might be helpful: /tmp/blk_kjdr1oog.log -Oh no! 💥 💔 💥 -1 file would fail to reformat. -$ echo $? -123 -``` - -#### `--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 `--color`. - -```console -$ black test.py --diff ---- 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") -would reformat test.py -All done! ✨ 🍰 ✨ -1 file would be reformatted. -``` - -#### `--color` / `--no-color` - -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 --version -black, 23.10.0 (compiled: yes) -$ black --required-version 23.10.0 -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 -``` - -#### `-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. - -```console -$ black src/ -v -Using configuration from /tmp/pyproject.toml. -src/blib2to3 ignored: matches the --extend-exclude regular expression -src/_black_version.py wasn't modified on disk since last run. -src/black/__main__.py wasn't modified on disk since last run. -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 -``` - -#### `--version` - -You can check the version of _Black_ you have installed using the `--version` flag. - -```console -$ black --version -black, 23.10.0 -``` - -#### `--config` - -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 -$ echo "print ( 'hello, world' )" | black - -print("hello, world") -reformatted - -All done! ✨ 🍰 ✨ -1 file reformatted. -``` - -**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 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. -``` - -The `--quiet` and `--verbose` flags control output verbosity. - -## Configuration via a file - -_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`/`--force-exclude`/`--extend-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. Applying those defaults will have your -code in compliance with many other _Black_ formatted projects. - -### 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://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 - -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 use a "global" configuration, stored in a specific location in your home -directory. This will be used as a fallback configuration, that is, it will be used if -and only if _Black_ doesn't find any configuration as mentioned above. Depending on your -operating system, this configuration file should be stored as: - -- Windows: `~\.black` -- Unix-like (Linux, MacOS, etc.): `$XDG_CONFIG_HOME/black` (`~/.config/black` if the - `XDG_CONFIG_HOME` environment variable is not set) - -Note that these are paths to the TOML file itself (meaning that they shouldn't be named -as `pyproject.toml`), not directories where you store the configuration. Here, `~` -refers to the path to your home directory. On Windows, this will be something like -`C:\\Users\UserName`. - -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. - -Please note `blackd` will not use `pyproject.toml` configuration. - -### 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 -target-version = ['py37'] -include = '\.pyi?$' -# 'extend-exclude' excludes files or directories in addition to the defaults -extend-exclude = ''' -# A regex preceded with ^/ will apply only to files and directories -# 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 -) -''' -``` - -
- -### 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. - -## Next steps - -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). - -Another good choice would be setting up an -[integration with your editor](../integrations/editors.md) of choice or with -[pre-commit for source version control](../integrations/source_version_control.md).