-`--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.
-
-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 `pyproject.toml`</summary>
-
-```toml
-[tool.black]
-line-length = 88
-target-version = ['py37']
-include = '\.pyi?$'
-exclude = '''
-
-(
- /(
- \.eggs # exclude a few common directories in the
- | \.git # root of the project
- | \.hg
- | \.mypy_cache
- | \.tox
- | \.venv
- | _build
- | buck-out
- | build
- | dist
- )/
- | foo.py # also separately exclude a file named foo.py in
- # the root of the project
-)
-'''
-```
-
-</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.
-
-## Editor integration
-
-### Emacs
-
-Use [proofit404/blacken](https://github.com/proofit404/blacken) or
-[Elpy](https://github.com/jorgenschaefer/elpy).
-
-### PyCharm/IntelliJ IDEA
-
-1. Install `black`.
-
-```console
-$ pip install black
-```
-
-2. Locate your `black` installation folder.
-
-On macOS / Linux / BSD:
-
-```console
-$ which black
-/usr/local/bin/black # possible location
-```
-
-On Windows:
-
-```console
-$ where black
-%LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe # possible location
-```
-
-3. Open External tools in PyCharm/IntelliJ IDEA
-
-On macOS:
-
-`PyCharm -> Preferences -> Tools -> External Tools`
-
-On Windows / Linux / BSD:
-
-`File -> Settings -> Tools -> External Tools`
-
-4. Click the + icon to add a new external tool with the following values:
-
- - Name: Black
- - Description: Black is the uncompromising Python code formatter.
- - Program: <install_location_from_step_2>
- - Arguments: `"$FilePath$"`
-
-5. Format the currently opened file by selecting `Tools -> External Tools -> black`.
-
- - Alternatively, you can set a keyboard shortcut by navigating to
- `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
-
-6. Optionally, run _Black_ on every file save:
-
- 1. Make sure you have the
- [File Watcher](https://plugins.jetbrains.com/plugin/7177-file-watchers) plugin
- installed.
- 2. Go to `Preferences or Settings -> Tools -> File Watchers` and click `+` to add a
- new watcher:
- - Name: Black
- - File type: Python
- - Scope: Project Files
- - Program: <install_location_from_step_2>
- - Arguments: `$FilePath$`
- - Output paths to refresh: `$FilePath$`
- - Working directory: `$ProjectFileDir$`
-
- - Uncheck "Auto-save edited files to trigger the watcher"
-
-### Wing IDE
-
-Wing supports black via the OS Commands tool, as explained in the Wing documentation on
-[pep8 formatting](https://wingware.com/doc/edit/pep8). The detailed procedure is:
-
-1. Install `black`.
-
-```console
-$ pip install black
-```
-
-2. Make sure it runs from the command line, e.g.
-
-```console
-$ black --help
-```
-
-3. In Wing IDE, activate the **OS Commands** panel and define the command **black** to
- execute black on the currently selected file:
-
-- Use the Tools -> OS Commands menu selection
-- click on **+** in **OS Commands** -> New: Command line..
- - Title: black
- - Command Line: black %s
- - I/O Encoding: Use Default
- - Key Binding: F1
- - [x] Raise OS Commands when executed
- - [x] Auto-save files before execution
- - [x] Line mode
-
-4. Select a file in the editor and press **F1** , or whatever key binding you selected
- in step 3, to reformat the file.
-
-### Vim
-
-Commands and shortcuts:
-
-- `:Black` to format the entire file (ranges not supported);
-- `:BlackUpgrade` to upgrade _Black_ inside the virtualenv;
-- `:BlackVersion` to get the current version of _Black_ inside the virtualenv.
-
-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` or `~/.local/share/nvim/black`)
-
-To install with [vim-plug](https://github.com/junegunn/vim-plug):
-
-```
-Plug 'psf/black', { 'branch': 'stable' }
-```
-
-or with [Vundle](https://github.com/VundleVim/Vundle.vim):
-
-```
-Plugin 'psf/black'
-```
-
-and execute the following in a terminal:
-
-```console
-$ cd ~/.vim/bundle/black
-$ git checkout origin/stable -b stable
-```
-
-or you can copy the plugin from
-[plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim).
-
-```
-mkdir -p ~/.vim/pack/python/start/black/plugin
-curl https://raw.githubusercontent.com/psf/black/master/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim
-```
-
-Let me know if this requires any changes to work with Vim 8's builtin `packadd`, or
-Pathogen, and so on.
-
-This plugin **requires Vim 7.0+ built with Python 3.6+ support**. It needs Python 3.6 to
-be able to run _Black_ inside the Vim process which is much faster than calling an
-external command.
-
-On first run, the plugin creates its own virtualenv using the right Python version and
-automatically installs _Black_. You can upgrade it later by calling `:BlackUpgrade` and
-restarting Vim.
-
-If you need to do anything special to make your virtualenv work and install _Black_ (for
-example you want to run a version from master), create a virtualenv manually and point
-`g:black_virtualenv` to it. The plugin will use it.
-
-To run _Black_ on save, add the following line to `.vimrc` or `init.vim`:
-
-```
-autocmd BufWritePre *.py execute ':Black'
-```
-
-To run _Black_ on a key press (e.g. F9 below), add this:
-
-```
-nnoremap <F9> :Black<CR>
-```
-
-**How to get Vim with Python 3.6?** On Ubuntu 17.10 Vim comes with Python 3.6 by
-default. On macOS with Homebrew run: `brew install vim`. When building Vim from source,
-use: `./configure --enable-python3interp=yes`. There's many guides online how to do
-this.
-
-### Visual Studio Code
-
-Use the
-[Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
-([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
-
-### SublimeText 3
-
-Use [sublack plugin](https://github.com/jgirardet/sublack).
-
-### Jupyter Notebook Magic
-
-Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
-
-### Python Language Server
projects / etc / vim.git / blobdiff