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

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