9451c57d1c
* Added support for top-level user configuration At the user level, a TOML config can be specified in the following locations: * Windows: ~\.black * Unix-like: $XDG_CONFIG_HOME/black (~/.config/black fallback) Instead of changing env vars for the entire black-primer process, they are now changed only for the black subprocess, using a tmpdir.
90 lines
3.7 KiB
Markdown
90 lines
3.7 KiB
Markdown
[//]: # "NOTE: THIS FILE WAS AUTOGENERATED FROM README.md"
|
|
|
|
# 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`/`--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.
|
|
|
|
## 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.
|
|
|
|
<details>
|
|
<summary>Example <code>pyproject.toml</code></summary>
|
|
|
|
```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)
|
|
'''
|
|
```
|
|
|
|
</details>
|
|
|
|
## 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.
|