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