-PEP 484 describes the syntax for type hints in Python. One of the
-use cases for typing is providing type annotations for modules which
-cannot contain them directly (they might be written in C, or they might
-be third-party, or their implementation may be overly dynamic, and so on).
-
-To solve this, [stub files with the `.pyi` file
-extension](https://www.python.org/dev/peps/pep-0484/#stub-files) can be
-used to describe typing information for an external module. Those stub
-files omit the implementation of classes and functions they
-describe, instead they only contain the structure of the file (listing
-globals, functions, and classes with their members). The recommended
-code style for those files is more terse than PEP 8:
-
-* prefer `...` on the same line as the class/function signature;
-* avoid vertical whitespace between consecutive module-level functions,
- names, or methods and fields within a single class;
-* use a single blank line between top-level class definitions, or none
- if the classes are very small.
-
-*Black* enforces the above rules. There are additional guidelines for
-formatting `.pyi` file that are not enforced yet but might be in
-a future version of the formatter:
-
-* all function bodies should be empty (contain `...` instead of the body);
-* do not use docstrings;
-* prefer `...` over `pass`;
-* for arguments with a default, use `...` instead of the actual default;
-* avoid using string literals in type annotations, stub files support
- forward references natively (like Python 3.7 code with `from __future__
- import annotations`);
-* use variable annotations instead of type comments, even for stubs that
- target older versions of Python;
-* for arguments that default to `None`, use `Optional[]` explicitly;
-* use `float` instead of `Union[int, float]`.
+PEP 484 describes the syntax for type hints in Python. One of the use cases for typing
+is providing type annotations for modules which cannot contain them directly (they might
+be written in C, or they might be third-party, or their implementation may be overly
+dynamic, and so on).
+
+To solve this,
+[stub files with the `.pyi` file extension](https://www.python.org/dev/peps/pep-0484/#stub-files)
+can be used to describe typing information for an external module. Those stub files omit
+the implementation of classes and functions they describe, instead they only contain the
+structure of the file (listing globals, functions, and classes with their members). The
+recommended code style for those files is more terse than PEP 8:
+
+- prefer `...` on the same line as the class/function signature;
+- avoid vertical whitespace between consecutive module-level functions, names, or
+ methods and fields within a single class;
+- use a single blank line between top-level class definitions, or none if the classes
+ are very small.
+
+_Black_ enforces the above rules. There are additional guidelines for formatting `.pyi`
+file that are not enforced yet but might be in a future version of the formatter:
+
+- all function bodies should be empty (contain `...` instead of the body);
+- do not use docstrings;
+- prefer `...` over `pass`;
+- for arguments with a default, use `...` instead of the actual default;
+- avoid using string literals in type annotations, stub files support forward references
+ natively (like Python 3.7 code with `from __future__ import annotations`);
+- use variable annotations instead of type comments, even for stubs that target older
+ versions of Python;
+- for arguments that default to `None`, use `Optional[]` explicitly;
+- use `float` instead of `Union[int, float]`.
+
+## 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` 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.
projects / etc / vim.git / blobdiff