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