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.
1 .. black documentation master file, created by
2 sphinx-quickstart on Fri Mar 23 10:53:30 2018.
4 The uncompromising code formatter
5 =================================
9 By using *Black*, you agree to cede control over minutiae of
10 hand-formatting. In return, *Black* gives you speed, determinism, and
11 freedom from `pycodestyle` nagging about formatting. You will save time
12 and mental energy for more important matters.
14 *Black* makes code review faster by producing the smallest diffs
15 possible. Blackened code looks the same regardless of the project
16 you're reading. Formatting becomes transparent after a while and you
17 can focus on the content instead.
19 Try it out now using the `Black Playground <https://black.vercel.app>`_.
21 .. admonition:: Note - this is a beta product
23 *Black* is already `successfully used <https://github.com/psf/black#used-by>`_ by
24 many projects, small and big. *Black* has a comprehensive test suite, with efficient
25 parallel tests, our own auto formatting and parallel Continuous Integration runner.
26 However, *Black* is still beta. Things will probably be wonky for a while. This is
27 made explicit by the "Beta" trove classifier, as well as by the "b" in the version
28 number. What this means for you is that **until the formatter becomes stable, you
29 should expect some formatting to change in the future**. That being said, no drastic
30 stylistic changes are planned, mostly responses to bug reports.
32 Also, as a safety measure which slows down processing, *Black* will check that the
33 reformatted code still produces a valid AST that is effectively equivalent to the
35 `Pragmatism <./the_black_code_style/current_style.html#pragmatism>`_
36 section for details). If you're feeling confident, use ``--fast``.
39 :doc:`Black is licensed under the MIT license <license>`.
44 **Mike Bayer**, author of `SQLAlchemy <https://www.sqlalchemy.org/>`_:
46 *I can't think of any single tool in my entire programming career that has given me a
47 bigger productivity increase by its introduction. I can now do refactorings in about
48 1% of the keystrokes that it would have taken me previously when we had no way for
49 code to format itself.*
51 **Dusty Phillips**, `writer <https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips>`_:
53 *Black is opinionated so you don't have to be.*
55 **Hynek Schlawack**, creator of `attrs <https://www.attrs.org/>`_, core
56 developer of Twisted and CPython:
58 *An auto-formatter that doesn't suck is all I want for Xmas!*
60 **Carl Meyer**, `Django <https://www.djangoproject.com/>`_ core developer:
62 *At least the name is good.*
64 **Kenneth Reitz**, creator of `requests <http://python-requests.org/>`_
65 and `pipenv <https://docs.pipenv.org/>`_:
67 *This vastly improves the formatting of our code. Thanks a ton!*
73 Use the badge in your project's README.md:
77 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
80 Using the badge in README.rst:
84 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
85 :target: https://github.com/psf/black
89 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
90 :target: https://github.com/psf/black
99 the_black_code_style/index
107 usage_and_configuration/index
115 :caption: Development
123 :caption: Project Links
125 GitHub <https://github.com/psf/black>
126 PyPI <https://pypi.org/project/black>
127 Chat <https://discord.gg/RtVdv86PrH>