X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/37a0020e073555ffe0921ec1356a27610aadcca4..f2ea461e9e9fa5c47bb61fd72d512c748928badc:/docs/compatible_configs.md?ds=inline diff --git a/docs/compatible_configs.md b/docs/compatible_configs.md index 25e959e..de81769 100644 --- a/docs/compatible_configs.md +++ b/docs/compatible_configs.md @@ -10,13 +10,33 @@ tools out there. (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. -### 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 @@ -32,7 +52,7 @@ line_length = 88 _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 separate 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". @@ -69,9 +89,6 @@ 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. -If only isort >= 5 is used you can add `profile = black` instead of all the options -since [profiles](https://timothycrosley.github.io/isort/docs/configuration/profiles/) -are available and do the configuring for you. ### Formats @@ -80,12 +97,7 @@ are available and do the configuring for you. ```cfg [settings] -multi_line_output = 3 -include_trailing_comma = True -force_grid_wrap = 0 -use_parentheses = True -ensure_newline_before_comments = True -line_length = 88 +profile = black ``` @@ -95,12 +107,7 @@ line_length = 88 ```cfg [isort] -multi_line_output = 3 -include_trailing_comma = True -force_grid_wrap = 0 -use_parentheses = True -ensure_newline_before_comments = True -line_length = 88 +profile = black ``` @@ -110,12 +117,7 @@ line_length = 88 ```toml [tool.isort] -multi_line_output = 3 -include_trailing_comma = true -force_grid_wrap = 0 -use_parentheses = true -ensure_newline_before_comments = true -line_length = 88 +profile = 'black' ``` @@ -125,12 +127,7 @@ line_length = 88 ```ini [*.py] -multi_line_output = 3 -include_trailing_comma = True -force_grid_wrap = 0 -use_parentheses = True -ensure_newline_before_comments = True -line_length = 88 +profile = black ``` @@ -146,21 +143,22 @@ There are a few deviations that cause incompatibilities with _Black_. ``` max-line-length = 88 -extend-ignore = E203, W503 +extend-ignore = E203 ``` ### 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 -`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`. @@ -173,7 +171,7 @@ limit of `88`, _Black_'s default. This explains `max-line-length = 88`. ```ini [flake8] max-line-length = 88 -extend-ignore = E203, W503 +extend-ignore = E203 ``` @@ -184,7 +182,7 @@ extend-ignore = E203, W503 ```cfg [flake8] max-line-length = 88 -extend-ignore = E203, W503 +extend-ignore = E203 ``` @@ -195,7 +193,7 @@ extend-ignore = E203, W503 ```ini [flake8] max-line-length = 88 -extend-ignore = E203, W503 +extend-ignore = E203 ``` @@ -217,7 +215,7 @@ max-line-length = 88 ### 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(