docs/compatible_configs.md

   1 # _Black_ compatible configurations
   2
   3 All of Black's changes are harmless (or at least, they should be), but a few do conflict
   4 against other tools. It is not uncommon to be using other tools alongside _Black_ like
   5 linters and type checkers. Some of them need a bit of tweaking to resolve the conflicts.
   6 Listed below are _Black_ compatible configurations in various formats for the common
   7 tools out there.
   8
   9 **Please note** that _Black_ only supports the TOML file format for its configuration
  10 (e.g. `pyproject.toml`). The provided examples are to only configure their corresponding
  11 tools, using **their** supported file formats.
  12
  13 Compatible configuration files can be
  14 [found here](https://github.com/psf/black/blob/master/docs/compatible_configs/).
  15
  16 ## isort
  17
  18 [isort](https://pypi.org/p/isort/) helps to sort and format imports in your Python code.
  19 _Black_ also formats imports, but in a different way from isort's defaults which leads
  20 to conflicting changes.
  21
  22 ### Configuration
  23
  24 ```
  25 multi_line_output = 3
  26 include_trailing_comma = True
  27 force_grid_wrap = 0
  28 use_parentheses = True
  29 ensure_newline_before_comments = True
  30 line_length = 88
  31 ```
  32
  33 ### Why those options above?
  34
  35 _Black_ wraps imports that surpass `line-length` by moving identifiers into their own
  36 indented line. If that still doesn't fit the bill, it will put all of them in separate
  37 lines and put a trailing comma. A more detailed explanation of this behaviour can be
  38 [found here](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#how-black-wraps-lines).
  39
  40 isort's default mode of wrapping imports that extend past the `line_length` limit is
  41 "Grid".
  42
  43 ```py3
  44 from third_party import (lib1, lib2, lib3,
  45                          lib4, lib5, ...)
  46 ```
  47
  48 This style is incompatible with _Black_, but isort can be configured to use a different
  49 wrapping mode called "Vertical Hanging Indent" which looks like this:
  50
  51 ```py3
  52 from third_party import (
  53     lib1,
  54     lib2,
  55     lib3,
  56     lib4,
  57 )
  58 ```
  59
  60 This style is _Black_ compatible and can be achieved by `multi-line-output = 3`. Also,
  61 as mentioned above, when wrapping long imports _Black_ puts a trailing comma and uses
  62 parentheses. isort should follow the same behaviour and passing the options
  63 `include_trailing_comma = True` and `use_parentheses = True` configures that.
  64
  65 The option `force_grid_wrap = 0` is just to tell isort to only wrap imports that surpass
  66 the `line_length` limit.
  67
  68 Finally, isort should be told to wrap imports when they surpass _Black_'s default limit
  69 of 88 characters via `line_length = 88` as well as
  70 `ensure_newline_before_comments = True` to ensure spacing import sections with comments
  71 works the same as with _Black_.
  72
  73 **Please note** `ensure_newline_before_comments = True` only works since isort >= 5 but
  74 does not break older versions so you can keep it if you are running previous versions.
  75 If only isort >= 5 is used you can add `profile = black` instead of all the options
  76 since [profiles](https://timothycrosley.github.io/isort/docs/configuration/profiles/)
  77 are available and do the configuring for you.
  78
  79 ### Formats
  80
  81 <details>
  82 <summary>.isort.cfg</summary>
  83
  84 ```cfg
  85 [settings]
  86 multi_line_output = 3
  87 include_trailing_comma = True
  88 force_grid_wrap = 0
  89 use_parentheses = True
  90 ensure_newline_before_comments = True
  91 line_length = 88
  92 ```
  93
  94 </details>
  95
  96 <details>
  97 <summary>setup.cfg</summary>
  98
  99 ```cfg
 100 [isort]
 101 multi_line_output = 3
 102 include_trailing_comma = True
 103 force_grid_wrap = 0
 104 use_parentheses = True
 105 ensure_newline_before_comments = True
 106 line_length = 88
 107 ```
 108
 109 </details>
 110
 111 <details>
 112 <summary>pyproject.toml</summary>
 113
 114 ```toml
 115 [tool.isort]
 116 multi_line_output = 3
 117 include_trailing_comma = true
 118 force_grid_wrap = 0
 119 use_parentheses = true
 120 ensure_newline_before_comments = true
 121 line_length = 88
 122 ```
 123
 124 </details>
 125
 126 <details>
 127 <summary>.editorconfig</summary>
 128
 129 ```ini
 130 [*.py]
 131 multi_line_output = 3
 132 include_trailing_comma = True
 133 force_grid_wrap = 0
 134 use_parentheses = True
 135 ensure_newline_before_comments = True
 136 line_length = 88
 137 ```
 138
 139 </details>
 140
 141 ## Flake8
 142
 143 [Flake8](https://pypi.org/p/flake8/) is a code linter. It warns you of syntax errors,
 144 possible bugs, stylistic errors, etc. For the most part, Flake8 follows
 145 [PEP 8](https://www.python.org/dev/peps/pep-0008/) when warning about stylistic errors.
 146 There are a few deviations that cause incompatibilities with _Black_.
 147
 148 ### Configuration
 149
 150 ```
 151 max-line-length = 88
 152 extend-ignore = E203
 153 ```
 154
 155 ### Why those options above?
 156
 157 In some cases, as determined by PEP 8, _Black_ will enforce an equal amount of
 158 whitespace around slice operators. Due to this, Flake8 will raise
 159 `E203 whitespace before ':'` warnings. Since this warning is not PEP 8 compliant, Flake8
 160 should be configured to ignore it via `extend-ignore = E203`.
 161
 162 When breaking a line, _Black_ will break it before a binary operator. This is compliant
 163 with PEP 8 as of
 164 [April 2016](https://github.com/python/peps/commit/c59c4376ad233a62ca4b3a6060c81368bd21e85b#diff-64ec08cc46db7540f18f2af46037f599).
 165 There's a disabled-by-default warning in Flake8 which goes against this PEP 8
 166 recommendation called `W503 line break before binary operator`. It should not be enabled
 167 in your configuration.
 168
 169 Also, as like with isort, flake8 should be configured to allow lines up to the length
 170 limit of `88`, _Black_'s default. This explains `max-line-length = 88`.
 171
 172 ### Formats
 173
 174 <details>
 175 <summary>.flake8</summary>
 176
 177 ```ini
 178 [flake8]
 179 max-line-length = 88
 180 extend-ignore = E203
 181 ```
 182
 183 </details>
 184
 185 <details>
 186 <summary>setup.cfg</summary>
 187
 188 ```cfg
 189 [flake8]
 190 max-line-length = 88
 191 extend-ignore = E203
 192 ```
 193
 194 </details>
 195
 196 <details>
 197 <summary>tox.ini</summary>
 198
 199 ```ini
 200 [flake8]
 201 max-line-length = 88
 202 extend-ignore = E203
 203 ```
 204
 205 </details>
 206
 207 ## Pylint
 208
 209 [Pylint](https://pypi.org/p/pylint/) is also a code linter like Flake8. It has the same
 210 checks as flake8 and more. In particular, it has more formatting checks regarding style
 211 conventions like variable naming. With so many checks, Pylint is bound to have some
 212 mixed feelings about _Black_'s formatting style.
 213
 214 ### Configuration
 215
 216 ```
 217 disable = C0330, C0326
 218 max-line-length = 88
 219 ```
 220
 221 ### Why those options above?
 222
 223 When _Black_ is folding very long expressions, the closing brackets will
 224 [be dedented](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#how-black-wraps-lines).
 225
 226 ```py3
 227 ImportantClass.important_method(
 228     exc, limit, lookup_lines, capture_locals, callback
 229 )
 230 ```
 231
 232 Although, this style is PEP 8 compliant, Pylint will raise
 233 `C0330: Wrong hanging indentation before block (add 4 spaces)` warnings. Since _Black_
 234 isn't configurable on this style, Pylint should be told to ignore these warnings via
 235 `disable = C0330`.
 236
 237 Also, since _Black_ deals with whitespace around operators and brackets, Pylint's
 238 warning `C0326: Bad whitespace` should be disabled using `disable = C0326`.
 239
 240 And as usual, Pylint should be configured to only complain about lines that surpass `88`
 241 characters via `max-line-length = 88`.
 242
 243 ### Formats
 244
 245 <details>
 246 <summary>pylintrc</summary>
 247
 248 ```ini
 249 [MESSAGES CONTROL]
 250 disable = C0330, C0326
 251
 252 [format]
 253 max-line-length = 88
 254 ```
 255
 256 </details>
 257
 258 <details>
 259 <summary>setup.cfg</summary>
 260
 261 ```cfg
 262 [pylint]
 263 max-line-length = 88
 264
 265 [pylint.messages_control]
 266 disable = C0330, C0326
 267 ```
 268
 269 </details>
 270
 271 <details>
 272 <summary>pyproject.toml</summary>
 273
 274 ```toml
 275 [tool.pylint.messages_control]
 276 disable = "C0330, C0326"
 277
 278 [tool.pylint.format]
 279 max-line-length = "88"
 280 ```
 281
 282 </details>