docs/guides/using_black_with_other_tools.md

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