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