Refactor `src/black/__init__.py` into many files (#2206)

[etc/vim.git] / docs / compatible_configs.md

diff --git a/docs/compatible_configs.md b/docs/compatible_configs.md
index e8267435323adf26c797217398f8cc5a32507b48..de81769f72dc46f296b7cc883c91f84b6cd506c4 100644 (file)
--- a/docs/compatible_configs.md
+++ b/docs/compatible_configs.md
@@ -6,28 +6,53 @@ linters and type checkers. Some of them need a bit of tweaking to resolve the co
 Listed below are _Black_ compatible configurations in various formats for the common
 tools out there.
 
 Listed below are _Black_ compatible configurations in various formats for the common
 tools out there.
 

+**Please note** that _Black_ only supports the TOML file format for its configuration
+(e.g. `pyproject.toml`). The provided examples are to only configure their corresponding
+tools, using **their** supported file formats.
+
+Compatible configuration files can be
+[found here](https://github.com/psf/black/blob/master/docs/compatible_configs/).
+

 ## isort
 
 [isort](https://pypi.org/p/isort/) helps to sort and format imports in your Python code.
 _Black_ also formats imports, but in a different way from isort's defaults which leads
 to conflicting changes.
 
 ## isort
 
 [isort](https://pypi.org/p/isort/) helps to sort and format imports in your Python code.
 _Black_ also formats imports, but in a different way from isort's defaults which leads
 to conflicting changes.
 

-### Configuration
+### Profile
+
+Since version 5.0.0, isort supports
+[profiles](https://pycqa.github.io/isort/docs/configuration/profiles/) to allow easy
+interoperability with common code styles. You can set the black profile in any of the
+[config files](https://pycqa.github.io/isort/docs/configuration/config_files/) supported
+by isort. Below, an example for `pyproject.toml`:
+
+```toml
+[tool.isort]
+profile = "black"
+```
+
+### Custom Configuration
+
+If you're using an isort version that is older than 5.0.0 or you have some custom
+configuration for _Black_, you can tweak your isort configuration to make it compatible
+with _Black_. Below, an example for `.isort.cfg`:

 
 ```
 multi_line_output = 3
 include_trailing_comma = True
 force_grid_wrap = 0
 use_parentheses = True
 
 ```
 multi_line_output = 3
 include_trailing_comma = True
 force_grid_wrap = 0
 use_parentheses = True

+ensure_newline_before_comments = True

 line_length = 88
 ```
 
 ### Why those options above?
 
 _Black_ wraps imports that surpass `line-length` by moving identifiers into their own
 line_length = 88
 ```
 
 ### Why those options above?
 
 _Black_ wraps imports that surpass `line-length` by moving identifiers into their own

-indented line. If that still doesn't fit the bill, it will put all of them in seperate
+indented line. If that still doesn't fit the bill, it will put all of them in separate

 lines and put a trailing comma. A more detailed explanation of this behaviour can be
 lines and put a trailing comma. A more detailed explanation of this behaviour can be

-[found here](https://github.com/psf/black#how-black-wraps-lines).
+[found here](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#how-black-wraps-lines).

 
 isort's default mode of wrapping imports that extend past the `line_length` limit is
 "Grid".
 
 isort's default mode of wrapping imports that extend past the `line_length` limit is
 "Grid".


@@ -58,7 +83,12 @@ The option `force_grid_wrap = 0` is just to tell isort to only wrap imports that
 the `line_length` limit.
 
 Finally, isort should be told to wrap imports when they surpass _Black_'s default limit
 the `line_length` limit.
 
 Finally, isort should be told to wrap imports when they surpass _Black_'s default limit

-of 88 characters via `line_length = 88`.
+of 88 characters via `line_length = 88` as well as
+`ensure_newline_before_comments = True` to ensure spacing import sections with comments
+works the same as with _Black_.
+
+**Please note** `ensure_newline_before_comments = True` only works since isort >= 5 but
+does not break older versions so you can keep it if you are running previous versions.

 
 ### Formats
 
 
 ### Formats
 


@@ -67,11 +97,7 @@ of 88 characters via `line_length = 88`.
 
 ```cfg
 [settings]
 
 ```cfg
 [settings]

-multi_line_output = 3
-include_trailing_comma = True
-force_grid_wrap = 0
-use_parentheses = True
-line_length = 88
+profile = black

 ```
 
 </details>
 ```
 
 </details>


@@ -81,11 +107,7 @@ line_length = 88
 
 ```cfg
 [isort]
 
 ```cfg
 [isort]

-multi_line_output = 3
-include_trailing_comma = True
-force_grid_wrap = 0
-use_parentheses = True
-line_length = 88
+profile = black

 ```
 
 </details>
 ```
 
 </details>


@@ -95,11 +117,7 @@ line_length = 88
 
 ```toml
 [tool.isort]
 
 ```toml
 [tool.isort]

-multi_line_output = 3
-include_trailing_comma = true
-force_grid_wrap = 0
-use_parentheses = true
-line_length = 88
+profile = 'black'

 ```
 
 </details>
 ```
 
 </details>


@@ -109,11 +127,7 @@ line_length = 88
 
 ```ini
 [*.py]
 
 ```ini
 [*.py]

-multi_line_output = 3
-include_trailing_comma = True
-force_grid_wrap = 0
-use_parentheses = True
-line_length = 88
+profile = black

 ```
 
 </details>
 ```
 
 </details>


@@ -129,21 +143,22 @@ There are a few deviations that cause incompatibilities with _Black_.
 
 ```
 max-line-length = 88
 
 ```
 max-line-length = 88

-extend-ignore = E203, W503
+extend-ignore = E203

 ```
 
 ### Why those options above?
 
 ```
 
 ### Why those options above?
 

-When breaking a line, _Black_ will break it before a binary operator. This is compliant
-with PEP 8, but this behaviour will cause flake8 to raise
-`W503 line break before binary operator` warnings.
-

 In some cases, as determined by PEP 8, _Black_ will enforce an equal amount of
 whitespace around slice operators. Due to this, Flake8 will raise
 In some cases, as determined by PEP 8, _Black_ will enforce an equal amount of
 whitespace around slice operators. Due to this, Flake8 will raise

-`E203 whitespace before ':'` warnings.
+`E203 whitespace before ':'` warnings. Since this warning is not PEP 8 compliant, Flake8
+should be configured to ignore it via `extend-ignore = E203`.

 
 

-Since both of these warnings are not PEP 8 compliant, Flake8 should be configured to
-ignore these warnings via `extend-ignore = E203, W503`.
+When breaking a line, _Black_ will break it before a binary operator. This is compliant
+with PEP 8 as of
+[April 2016](https://github.com/python/peps/commit/c59c4376ad233a62ca4b3a6060c81368bd21e85b#diff-64ec08cc46db7540f18f2af46037f599).
+There's a disabled-by-default warning in Flake8 which goes against this PEP 8
+recommendation called `W503 line break before binary operator`. It should not be enabled
+in your configuration.

 
 Also, as like with isort, flake8 should be configured to allow lines up to the length
 limit of `88`, _Black_'s default. This explains `max-line-length = 88`.
 
 Also, as like with isort, flake8 should be configured to allow lines up to the length
 limit of `88`, _Black_'s default. This explains `max-line-length = 88`.


@@ -156,7 +171,7 @@ limit of `88`, _Black_'s default. This explains `max-line-length = 88`.
 ```ini
 [flake8]
 max-line-length = 88
 ```ini
 [flake8]
 max-line-length = 88

-extend-ignore = E203, W503
+extend-ignore = E203

 ```
 
 </details>
 ```
 
 </details>


@@ -167,7 +182,7 @@ extend-ignore = E203, W503
 ```cfg
 [flake8]
 max-line-length = 88
 ```cfg
 [flake8]
 max-line-length = 88

-extend-ignore = E203, W503
+extend-ignore = E203

 ```
 
 </details>
 ```
 
 </details>


@@ -178,7 +193,7 @@ extend-ignore = E203, W503
 ```ini
 [flake8]
 max-line-length = 88
 ```ini
 [flake8]
 max-line-length = 88

-extend-ignore = E203, W503
+extend-ignore = E203

 ```
 
 </details>
 ```
 
 </details>


@@ -200,7 +215,7 @@ max-line-length = 88
 ### Why those options above?
 
 When _Black_ is folding very long expressions, the closing brackets will
 ### Why those options above?
 
 When _Black_ is folding very long expressions, the closing brackets will

-[be dedented](https://github.com/psf/black#how-black-wraps-lines).
+[be dedented](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#how-black-wraps-lines).

 
 ```py3
 ImportantClass.important_method(
 
 ```py3
 ImportantClass.important_method(


@@ -224,7 +239,7 @@ characters via `max-line-length = 88`.
 <details>
 <summary>pylintrc</summary>
 
 <details>
 <summary>pylintrc</summary>
 

-```rc
+```ini

 [MESSAGES CONTROL]
 disable = C0330, C0326
 
 [MESSAGES CONTROL]
 disable = C0330, C0326