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

b5ebfa005452fcac322c0844b9e35211f8c014b7
[etc/vim.git] / README.md
1 # black
2
3 [![Build Status](https://travis-ci.org/ambv/black.svg?branch=master)](https://travis-ci.org/ambv/black)
4
5 > Any color you like.
6
7
8 *Black* is the uncompromising Python code formatter.  By using it, you
9 agree to cease control over minutiae of hand-formatting.  In return,
10 *Black* gives you speed, determinism, and freedom from `pycodestyle`
11 nagging about formatting.  You will save time and mental energy for
12 more important matters.
13
14 Blackened code looks the same regardless of the project you're reading.
15 Formatting becomes transparent after a while and you can focus on the
16 content instead.
17
18 *Black* makes code review faster by producing the smallest diffs
19 possible.
20
21
22 ## NOTE: This is an early pre-release
23
24 *Black* can already successfully format itself and the standard library.
25 It also sports a decent test suite.  However, it is still very new.
26 Things will probably be wonky for a while. This is made explicit by the
27 "Alpha" trove classifier, as well as by the "a" in the version number.
28 What this means for you is that **until the formatter becomes stable,
29 you should expect some formatting to change in the future**.
30
31 Also, as a temporary safety measure, *Black* will check that the
32 reformatted code still produces a valid AST that is equivalent to the
33 original.  This slows it down.  If you're feeling confident, use
34 ``--fast``.
35
36
37 ## Usage
38
39 *Black* can be installed by running `pip install black`.
40
41 ```
42 black [OPTIONS] [SRC]...
43
44 Options:
45   -l, --line-length INTEGER   Where to wrap around.  [default: 88]
46   --check                     Don't write back the files, just return the
47                               status.  Return code 0 means nothing changed.
48                               Return code 1 means some files were reformatted.
49                               Return code 123 means there was an internal
50                               error.
51   --fast / --safe             If --fast given, skip temporary sanity checks.
52                               [default: --safe]
53   --version                   Show the version and exit.
54   --help                      Show this message and exit.
55 ```
56
57
58 ## The philosophy behind *Black*
59
60 *Black* reformats entire files in place.  It is not configurable.  It
61 doesn't take previous formatting into account.  It doesn't reformat
62 blocks that start with `# fmt: off` and end with `# fmt: on`.  It also
63 recognizes [YAPF](https://github.com/google/yapf)'s block comments to
64 the same effect, as a courtesy for straddling code.
65
66
67 ### How *Black* formats files
68
69 *Black* ignores previous formatting and applies uniform horizontal
70 and vertical whitespace to your code.  The rules for horizontal
71 whitespace are pretty obvious and can be summarized as: do whatever
72 makes `pycodestyle` happy.
73
74 As for vertical whitespace, *Black* tries to render one full expression
75 or simple statement per line.  If this fits the allotted line length,
76 great.
77 ```py3
78 # in:
79
80 l = [1,
81      2,
82      3,
83 ]
84
85 # out:
86
87 l = [1, 2, 3]
88 ```
89
90 If not, *Black* will look at the contents of the first outer matching
91 brackets and put that in a separate indented line.
92 ```py3
93 # in:
94
95 l = [[n for n in list_bosses()], [n for n in list_employees()]]
96
97 # out:
98
99 l = [
100     [n for n in list_bosses()], [n for n in list_employees()]
101 ]
102 ```
103
104 If that still doesn't fit the bill, it will decompose the internal
105 expression further using the same rule, indenting matching brackets
106 every time.  If the contents of the matching brackets pair are
107 comma-separated (like an argument list, or a dict literal, and so on)
108 then *Black* will first try to keep them on the same line with the
109 matching brackets.  If that doesn't work, it will put all of them in
110 separate lines.
111 ```py3
112 # in:
113
114 def very_important_function(template: str, *variables, file: os.PathLike, debug: bool = False):
115     """Applies `variables` to the `template` and writes to `file`."""
116     with open(file, 'w') as f:
117         ...
118
119 # out:
120
121 def very_important_function(
122     template: str,
123     *variables,
124     file: os.PathLike,
125     debug: bool = False,
126 ):
127     """Applies `variables` to the `template` and writes to `file`."""
128     with open(file, 'w') as f:
129         ...
130 ```
131
132 You might have noticed that closing brackets are always dedented and
133 that a trailing comma is always added.  Such formatting produces smaller
134 diffs; when you add or remove an element, it's always just one line.
135 Also, having the closing bracket dedented provides a clear delimiter
136 between two distinct sections of the code that otherwise share the same
137 indentation level (like the arguments list and the docstring in the
138 example above).
139
140 Unnecessary trailing commas are removed if an expression fits in one
141 line.  This makes it 1% more likely that your line won't exceed the
142 allotted line length limit.
143
144 *Black* avoids spurious vertical whitespace.  This is in the spirit of
145 PEP 8 which says that in-function vertical whitespace should only be
146 used sparingly.  One exception is control flow statements: *Black* will
147 always emit an extra empty line after ``return``, ``raise``, ``break``,
148 ``continue``, and ``yield``.  This is to make changes in control flow
149 more prominent to readers of your code.
150
151 That's it.  The rest of the whitespace formatting rules follow PEP 8 and
152 are designed to keep `pycodestyle` quiet.
153
154
155 ### Line length
156
157 You probably noticed the peculiar default line length.  *Black* defaults
158 to 88 characters per line, which happens to be 10% over 80.  This number
159 was found to produce significantly shorter files than sticking with 80
160 (the most popular), or even 79 (used by the standard library).  In
161 general, [90-ish seems like the wise choice](https://youtu.be/wf-BqAjZb8M?t=260).
162
163 If you're paid by the line of code you write, you can pass
164 `--line-length` with a lower number.  *Black* will try to respect that.
165 However, sometimes it won't be able to without breaking other rules.  In
166 those rare cases, auto-formatted code will exceed your allotted limit.
167
168 You can also increase it, but remember that people with sight disabilities
169 find it harder to work with line lengths exceeding 100 characters.
170 It also adversely affects side-by-side diff review  on typical screen
171 resolutions.  Long lines also make it harder to present code neatly
172 in documentation or talk slides.
173
174 If you're using Flake8, you can bump `max-line-length` to 88 and forget
175 about it.  Alternatively, use [Bugbear](https://github.com/PyCQA/flake8-bugbear)'s
176 B950 warning instead of E501 and keep the max line length at 80 which
177 you are probably already using.  You'd do it like this:
178 ```ini
179 [flake8]
180 max-line-length = 80
181 ...
182 select = C,E,F,W,B,B950
183 ignore = E501
184 ```
185
186 You'll find *Black*'s own .flake8 config file is configured like this.
187 If you're curious about the reasoning behind B950, Bugbear's documentation
188 explains it.  The tl;dr is "it's like highway speed limits, we won't
189 bother you if you overdo it by a few km/h".
190
191
192 ### Empty lines
193
194 *Black* will allow single empty lines left by the original editors,
195 except when they're added within parenthesized expressions.  Since such
196 expressions are always reformatted to fit minimal space, this whitespace
197 is lost.
198
199 It will also insert proper spacing before and after function definitions.
200 It's one line before and after inner functions and two lines before and
201 after module-level functions.  *Black* will put those empty lines also
202 between the function definition and any standalone comments that
203 immediately precede the given function.  If you want to comment on the
204 entire function, use a docstring or put a leading comment in the function
205 body.
206
207
208 ### Editor integration
209
210 * Visual Studio Code: [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode)
211
212 There is currently no integration with any other text editors. Vim and
213 Atom/Nuclide integration is planned by the author, others will require
214 external contributions.
215
216 Patches welcome! ✨ 🍰 ✨
217
218
219 ## Testimonials
220
221 **Dusty Phillips**, [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):
222
223 > Black is opinionated so you don't have to be.
224
225 **Hynek Schlawack**, [creator of `attrs`](http://www.attrs.org/), core
226 developer of Twisted and CPython:
227
228 > An auto-formatter that doesn't suck is all I want for Xmas!
229
230 **Carl Meyer**, [Django](https://www.djangoproject.com/) core developer:
231
232 > At least the name is good.
233
234 **Kenneth Reitz**, creator of [`requests`](http://python-requests.org/)
235 and [`pipenv`](https://docs.pipenv.org/):
236
237 > This vastly improves the formatting of our code. Thanks a ton!
238
239
240 ## Tests
241
242 Just run:
243
244 ```
245 python setup.py test
246 ```
247
248 ## This tool requires Python 3.6.0+ to run
249
250 But you can reformat Python 2 code with it, too.  *Black* is able to parse
251 all of the new syntax supported on Python 3.6 but also *effectively all*
252 the Python 2 syntax at the same time, as long as you're not using print
253 statements.
254
255 By making the code exclusively Python 3.6+, I'm able to focus on the
256 quality of the formatting and re-use all the nice features of the new
257 releases (check out [pathlib](https://docs.python.org/3/library/pathlib.html) or
258 f-strings) instead of wasting cycles on Unicode compatibility, and so on.
259
260
261 ## License
262
263 MIT
264
265
266 ## Contributing
267
268 In terms of inspiration, *Black* is about as configurable as *gofmt* and
269 *rustfmt* are.  This is deliberate.
270
271 Bug reports and fixes are always welcome!  However, before you suggest a
272 new feature or configuration knob, ask yourself why you want it.  If it
273 enables better integration with some workflow, fixes an inconsistency,
274 speeds things up, and so on - go for it!  On the other hand, if your
275 answer is "because I don't like a particular formatting" then you're not
276 ready to embrace *Black* yet. Such changes are unlikely to get accepted.
277 You can still try but prepare to be disappointed.
278
279 More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
280
281
282 ## Change Log
283
284 ### 18.3a3
285
286 * don't remove single empty lines outside of bracketed expressions
287   (#19)
288
289 * added ability to pipe formatting from stdin to stdin (#25)
290
291 * restored ability to format code with legacy usage of `async` as
292   a name (#20, #42)
293
294 * even better handling of numpy-style array indexing (#33, again)
295
296
297 ### 18.3a2
298
299 * changed positioning of binary operators to occur at beginning of lines
300   instead of at the end, following [a recent change to PEP8](https://github.com/python/peps/commit/c59c4376ad233a62ca4b3a6060c81368bd21e85b)
301   (#21)
302
303 * ignore empty bracket pairs while splitting. This avoids very weirdly
304   looking formattings (#34, #35)
305
306 * remove a trailing comma if there is a single argument to a call
307
308 * if top level functions were separated by a comment, don't put four
309   empty lines after the upper function
310
311 * fixed unstable formatting of newlines with imports
312
313 * fixed unintentional folding of post scriptum standalone comments
314   into last statement if it was a simple statement (#18, #28)
315
316 * fixed missing space in numpy-style array indexing (#33)
317
318 * fixed spurious space after star-based unary expressions (#31)
319
320
321 ### 18.3a1
322
323 * added `--check`
324
325 * only put trailing commas in function signatures and calls if it's
326   safe to do so. If the file is Python 3.6+ it's always safe, otherwise
327   only safe if there are no `*args` or `**kwargs` used in the signature
328   or call. (#8)
329
330 * fixed invalid spacing of dots in relative imports (#6, #13)
331
332 * fixed invalid splitting after comma on unpacked variables in for-loops
333   (#23)
334
335 * fixed spurious space in parenthesized set expressions (#7)
336
337 * fixed spurious space after opening parentheses and in default
338   arguments (#14, #17)
339
340 * fixed spurious space after unary operators when the operand was
341   a complex expression (#15)
342
343
344 ### 18.3a0
345
346 * first published version, Happy 🍰 Day 2018!
347
348 * alpha quality
349
350 * date-versioned (see: https://calver.org/)
351
352
353 ## Authors
354
355 Glued together by [Łukasz Langa](mailto:lukasz@langa.pl).