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

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