X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/8c3c190f9978d08b8b6e505112a019a20cc9e6fc..a669b64091c149132f4e234abd230f7b33d692e8:/docs/compatible_configs.md diff --git a/docs/compatible_configs.md b/docs/compatible_configs.md index b182f57..a4f83ee 100644 --- a/docs/compatible_configs.md +++ b/docs/compatible_configs.md @@ -6,6 +6,13 @@ 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. @@ -19,15 +26,16 @@ 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 +66,15 @@ 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. +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 @@ -71,6 +87,7 @@ multi_line_output = 3 include_trailing_comma = True force_grid_wrap = 0 use_parentheses = True +ensure_newline_before_comments = True line_length = 88 ``` @@ -85,6 +102,7 @@ multi_line_output = 3 include_trailing_comma = True force_grid_wrap = 0 use_parentheses = True +ensure_newline_before_comments = True line_length = 88 ``` @@ -96,9 +114,10 @@ line_length = 88 ```toml [tool.isort] multi_line_output = 3 -include_trailing_comma = True +include_trailing_comma = true force_grid_wrap = 0 -use_parentheses = True +use_parentheses = true +ensure_newline_before_comments = true line_length = 88 ``` @@ -113,6 +132,7 @@ multi_line_output = 3 include_trailing_comma = True force_grid_wrap = 0 use_parentheses = True +ensure_newline_before_comments = True line_length = 88 ``` @@ -129,21 +149,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 +177,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 +188,7 @@ extend-ignore = E203, W503 ```cfg [flake8] max-line-length = 88 -extend-ignore = E203, W503 +extend-ignore = E203 ``` @@ -178,7 +199,7 @@ extend-ignore = E203, W503 ```ini [flake8] max-line-length = 88 -extend-ignore = E203, W503 +extend-ignore = E203 ``` @@ -200,7 +221,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 +245,7 @@ characters via `max-line-length = 88`.
pylintrc -```rc +```ini [MESSAGES CONTROL] disable = C0330, C0326