]> 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:

990820a67716226ad095bf79cbfa9d7ab60cf24d
[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 ## 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>