X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/2f3fa1f6d0cbc2a3f31c7440c422da173b068e7b:/docs/usage_and_configuration/the_basics.md..dc71922c768e543c9c3bbb1db5ea6d7fa801a814:/.vim/bundle/black/docs/usage_and_configuration/static/gitweb.js diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md deleted file mode 100644 index 49268b4..0000000 --- a/docs/usage_and_configuration/the_basics.md +++ /dev/null @@ -1,292 +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 no sources are passed to it; -- 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 `--check` was used). - -## 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 - -_Black_ has quite a few knobs these days, although _Black_ is opinionated so style -configuration options are deliberately limited and rarely added. You can list them by -running `black --help`. - -
- -Help output - -```{program-output} black --help - -``` - -
- -### Code input alternatives - -#### Standard Input - -_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. - -#### As a string - -You can also pass code as a string using the `-c` / `--code` option. - -```console -$ black --code "print ( 'hello, world' )" -print("hello, world") -``` - -### 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. Both variations can be enabled at once. - -#### Exit code - -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 -``` - -#### Diffs - -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`. - -```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 -@@ -1 +1 @@ --print ( 'hello, world' ) -+print("hello, world") -would reformat test.py -All done! ✨ 🍰 ✨ -1 file would be reformatted. -``` - -### 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. -``` - -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 -``` - -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`). - -```console -$ black src/ -q -error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio -``` - -### Versions - -You can check the version of _Black_ you have installed using the `--version` flag. - -```console -$ black --version -black, version 21.9b0 -``` - -An option to require a specific version to be running is also provided. - -```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! -``` - -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. - -## 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/) 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 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 = ''' -# 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 (in addition to the defaults) -''' -``` - -
- -### 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 - -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). - -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).