X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/8c3c190f9978d08b8b6e505112a019a20cc9e6fc..5316836393682c6ec6a05d69c549d8167f46d8f6:/docs/compatible_configs.md?ds=inline diff --git a/docs/compatible_configs.md b/docs/compatible_configs.md index b182f57..de81769 100644 --- 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. +**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. -### 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 +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 -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 -[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". @@ -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 -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 @@ -67,11 +97,7 @@ of 88 characters via `line_length = 88`. ```cfg [settings] -multi_line_output = 3 -include_trailing_comma = True -force_grid_wrap = 0 -use_parentheses = True -line_length = 88 +profile = black ``` @@ -81,11 +107,7 @@ line_length = 88 ```cfg [isort] -multi_line_output = 3 -include_trailing_comma = True -force_grid_wrap = 0 -use_parentheses = True -line_length = 88 +profile = black ``` @@ -95,11 +117,7 @@ line_length = 88 ```toml [tool.isort] -multi_line_output = 3 -include_trailing_comma = True -force_grid_wrap = 0 -use_parentheses = True -line_length = 88 +profile = 'black' ``` @@ -109,11 +127,7 @@ line_length = 88 ```ini [*.py] -multi_line_output = 3 -include_trailing_comma = True -force_grid_wrap = 0 -use_parentheses = True -line_length = 88 +profile = black ``` @@ -129,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`. @@ -156,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 ``` @@ -167,7 +182,7 @@ extend-ignore = E203, W503 ```cfg [flake8] max-line-length = 88 -extend-ignore = E203, W503 +extend-ignore = E203 ``` @@ -178,7 +193,7 @@ extend-ignore = E203, W503 ```ini [flake8] max-line-length = 88 -extend-ignore = E203, W503 +extend-ignore = E203 ``` @@ -200,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( @@ -224,7 +239,7 @@ characters via `max-line-length = 88`.
pylintrc -```rc +```ini [MESSAGES CONTROL] disable = C0330, C0326