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

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