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