]> git.madduck.net Git - etc/vim.git/blob - docs/compatible_configs.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:

Speed up tests even more (#2205)
[etc/vim.git] / 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>