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

Docs: no space is inserted to empty docstrings (#2249) (#2333)
[etc/vim.git] / README.md
1 ![Black Logo](https://raw.githubusercontent.com/psf/black/main/docs/_static/logo2-readme.png)
2
3 <h2 align="center">The Uncompromising Code Formatter</h2>
4
5 <p align="center">
6 <a href="https://github.com/psf/black/actions"><img alt="Actions Status" src="https://github.com/psf/black/workflows/Test/badge.svg"></a>
7 <a href="https://github.com/psf/black/actions"><img alt="Actions Status" src="https://github.com/psf/black/workflows/Primer/badge.svg"></a>
8 <a href="https://black.readthedocs.io/en/stable/?badge=stable"><img alt="Documentation Status" src="https://readthedocs.org/projects/black/badge/?version=stable"></a>
9 <a href="https://coveralls.io/github/psf/black?branch=main"><img alt="Coverage Status" src="https://coveralls.io/repos/github/psf/black/badge.svg?branch=main"></a>
10 <a href="https://github.com/psf/black/blob/main/LICENSE"><img alt="License: MIT" src="https://black.readthedocs.io/en/stable/_static/license.svg"></a>
11 <a href="https://pypi.org/project/black/"><img alt="PyPI" src="https://img.shields.io/pypi/v/black"></a>
12 <a href="https://pepy.tech/project/black"><img alt="Downloads" src="https://pepy.tech/badge/black"></a>
13 <a href="https://anaconda.org/conda-forge/black/"><img alt="conda-forge" src="https://img.shields.io/conda/dn/conda-forge/black.svg?label=conda-forge"></a>
14 <a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
15 </p>
16
17 > “Any color you like.”
18
19 _Black_ is the uncompromising Python code formatter. By using it, you agree to cede
20 control over minutiae of hand-formatting. In return, _Black_ gives you speed,
21 determinism, and freedom from `pycodestyle` nagging about formatting. You will save time
22 and mental energy for more important matters.
23
24 Blackened code looks the same regardless of the project you're reading. Formatting
25 becomes transparent after a while and you can focus on the content instead.
26
27 _Black_ makes code review faster by producing the smallest diffs possible.
28
29 Try it out now using the [Black Playground](https://black.vercel.app). Watch the
30 [PyCon 2019 talk](https://youtu.be/esZLCuWs_2Y) to learn more.
31
32 ---
33
34 **[Read the documentation on ReadTheDocs!](https://black.readthedocs.io/en/stable)**
35
36 ---
37
38 ## Installation and usage
39
40 ### Installation
41
42 _Black_ can be installed by running `pip install black`. It requires Python 3.6.2+ to
43 run. If you want to format Python 2 code as well, install with
44 `pip install black[python2]`.
45
46 If you can't wait for the latest _hotness_ and want to install from GitHub, use:
47
48 `pip install git+git://github.com/psf/black`
49
50 ### Usage
51
52 To get started right away with sensible defaults:
53
54 ```sh
55 black {source_file_or_directory}
56 ```
57
58 You can run _Black_ as a package if running it as a script doesn't work:
59
60 ```sh
61 python -m black {source_file_or_directory}
62 ```
63
64 Further information can be found in our docs:
65
66 - [Usage and Configuration](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)
67
68 ### NOTE: This is a beta product
69
70 _Black_ is already [successfully used](https://github.com/psf/black#used-by) by many
71 projects, small and big. Black has a comprehensive test suite, with efficient parallel
72 tests, and our own auto formatting and parallel Continuous Integration runner. However,
73 _Black_ is still beta. Things will probably be wonky for a while. This is made explicit
74 by the "Beta" trove classifier, as well as by the "b" in the version number. What this
75 means for you is that **until the formatter becomes stable, you should expect some
76 formatting to change in the future**. That being said, no drastic stylistic changes are
77 planned, mostly responses to bug reports.
78
79 Also, as a safety measure which slows down processing, _Black_ will check that the
80 reformatted code still produces a valid AST that is effectively equivalent to the
81 original (see the
82 [Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#ast-before-and-after-formatting)
83 section for details). If you're feeling confident, use `--fast`.
84
85 ## The _Black_ code style
86
87 _Black_ is a PEP 8 compliant opinionated formatter. _Black_ reformats entire files in
88 place. Style configuration options are deliberately limited and rarely added. It doesn't
89 take previous formatting into account (see [Pragmatism](#pragmatism) for exceptions).
90
91 Our documentation covers the current _Black_ code style, but planned changes to it are
92 also documented. They're both worth taking a look:
93
94 - [The _Black_ Code Style: Current style](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html)
95 - [The _Black_ Code Style: Future style](https://black.readthedocs.io/en/stable/the_black_code_style/future_style.html)
96
97 Please refer to this document before submitting an issue. What seems like a bug might be
98 intended behaviour.
99
100 ### Pragmatism
101
102 Early versions of _Black_ used to be absolutist in some respects. They took after its
103 initial author. This was fine at the time as it made the implementation simpler and
104 there were not many users anyway. Not many edge cases were reported. As a mature tool,
105 _Black_ does make some exceptions to rules it otherwise holds.
106
107 - [The _Black_ code style: Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#pragmatism)
108
109 Please refer to this document before submitting an issue just like with the document
110 above. What seems like a bug might be intended behaviour.
111
112 ## Configuration
113
114 _Black_ is able to read project-specific default values for its command line options
115 from a `pyproject.toml` file. This is especially useful for specifying custom
116 `--include` and `--exclude`/`--force-exclude`/`--extend-exclude` patterns for your
117 project.
118
119 You can find more details in our documentation:
120
121 - [The basics: Configuration via a file](https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-via-a-file)
122
123 And if you're looking for more general configuration documentation:
124
125 - [Usage and Configuration](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)
126
127 **Pro-tip**: If you're asking yourself "Do I need to configure anything?" the answer is
128 "No". _Black_ is all about sensible defaults. Applying those defaults will have your
129 code in compliance with many other _Black_ formatted projects.
130
131 ## Used by
132
133 The following notable open-source projects trust _Black_ with enforcing a consistent
134 code style: pytest, tox, Pyramid, Django Channels, Hypothesis, attrs, SQLAlchemy,
135 Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow,
136 every Datadog Agent Integration, Home Assistant, Zulip.
137
138 The following organizations use _Black_: Facebook, Dropbox, Mozilla, Quora.
139
140 Are we missing anyone? Let us know.
141
142 ## Testimonials
143
144 **Mike Bayer**, [author of `SQLAlchemy`](https://www.sqlalchemy.org/):
145
146 > I can't think of any single tool in my entire programming career that has given me a
147 > bigger productivity increase by its introduction. I can now do refactorings in about
148 > 1% of the keystrokes that it would have taken me previously when we had no way for
149 > code to format itself.
150
151 **Dusty Phillips**,
152 [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):
153
154 > _Black_ is opinionated so you don't have to be.
155
156 **Hynek Schlawack**, [creator of `attrs`](https://www.attrs.org/), core developer of
157 Twisted and CPython:
158
159 > An auto-formatter that doesn't suck is all I want for Xmas!
160
161 **Carl Meyer**, [Django](https://www.djangoproject.com/) core developer:
162
163 > At least the name is good.
164
165 **Kenneth Reitz**, creator of [`requests`](http://python-requests.org/) and
166 [`pipenv`](https://readthedocs.org/projects/pipenv/):
167
168 > This vastly improves the formatting of our code. Thanks a ton!
169
170 ## Show your style
171
172 Use the badge in your project's README.md:
173
174 ```md
175 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
176 ```
177
178 Using the badge in README.rst:
179
180 ```
181 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
182     :target: https://github.com/psf/black
183 ```
184
185 Looks like this:
186 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
187
188 ## License
189
190 MIT
191
192 ## Contributing
193
194 Welcome! Happy to see you willing to make the project better. You can get started by
195 reading this:
196
197 - [Contributing: The basics](https://black.readthedocs.io/en/latest/contributing/the_basics.html)
198
199 You can also take a look at the rest of the contributing docs or talk with the
200 developers:
201
202 - [Contributing documentation](https://black.readthedocs.io/en/latest/contributing/index.html)
203 - [IRC channel on Freenode](https://webchat.freenode.net/?channels=%23blackformatter)
204
205 ## Change log
206
207 The log has become rather long. It moved to its own file.
208
209 See [CHANGES](https://black.readthedocs.io/en/latest/change_log.html).
210
211 ## Authors
212
213 The author list is quite long nowadays, so it lives in its own file.
214
215 See [AUTHORS.md](./AUTHORS.md)
216
217 ## Code of Conduct
218
219 Everyone participating in the _Black_ project, and in particular in the issue tracker,
220 pull requests, and social media activity, is expected to treat other people with respect
221 and more generally to follow the guidelines articulated in the
222 [Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/).
223
224 At the same time, humor is encouraged. In fact, basic familiarity with Monty Python's
225 Flying Circus is expected. We are not savages.
226
227 And if you _really_ need to slap somebody, do it with a fish while dancing.