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

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