]> git.madduck.net Git - etc/vim.git/blob - docs/guides/using_black_with_other_tools.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Draft for Black 2023 stable style (#3418)
[etc/vim.git] / 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 into their own
55 indented line. If that still doesn't fit the bill, it will put all of them in separate
56 lines and put a trailing comma. A more detailed explanation of this 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>