Stubs: preserve blank line between attributes and methods (#2736)

[etc/vim.git] / README.md

diff --git a/README.md b/README.md
index b1c74b5a8d7d2e373d828e78c80faf1c1b52a0ee..2adf60a783a1cd8c77d0e89010a97ecafa96c122 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,300 +1,230 @@
-# black
+![Black Logo](https://raw.githubusercontent.com/psf/black/main/docs/_static/logo2-readme.png)

 
 

-[![Build Status](https://travis-ci.org/ambv/black.svg?branch=master)](https://travis-ci.org/ambv/black)
+<h2 align="center">The Uncompromising Code Formatter</h2>

 
 

-> Any color you like.
+<p align="center">
+<a href="https://github.com/psf/black/actions"><img alt="Actions Status" src="https://github.com/psf/black/workflows/Test/badge.svg"></a>
+<a href="https://github.com/psf/black/actions"><img alt="Actions Status" src="https://github.com/psf/black/workflows/Primer/badge.svg"></a>
+<a href="https://black.readthedocs.io/en/stable/?badge=stable"><img alt="Documentation Status" src="https://readthedocs.org/projects/black/badge/?version=stable"></a>
+<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>
+<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>
+<a href="https://pypi.org/project/black/"><img alt="PyPI" src="https://img.shields.io/pypi/v/black"></a>
+<a href="https://pepy.tech/project/black"><img alt="Downloads" src="https://pepy.tech/badge/black"></a>
+<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>
+<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
+</p>

 
 

+> “Any color you like.”

 
 

-*Black* is the uncompromising Python code formatter.  By using it, you
-agree to cease control over minutiae of hand-formatting.  In return,
-*Black* gives you speed, determinism, and freedom from `pycodestyle`
-nagging about formatting.  You will save time and mental energy for
-more important matters.
+_Black_ is the uncompromising Python code formatter. By using it, you agree to cede
+control over minutiae of hand-formatting. In return, _Black_ gives you speed,
+determinism, and freedom from `pycodestyle` nagging about formatting. You will save time
+and mental energy for more important matters.

 
 

-Blackened code looks the same regardless of the project you're reading.
-Formatting becomes transparent after a while and you can focus on the
-content instead.
+Blackened code looks the same regardless of the project you're reading. Formatting
+becomes transparent after a while and you can focus on the content instead.

 
 

-*Black* makes code review faster by producing the smallest diffs
-possible.
+_Black_ makes code review faster by producing the smallest diffs possible.

 
 

+Try it out now using the [Black Playground](https://black.vercel.app). Watch the
+[PyCon 2019 talk](https://youtu.be/esZLCuWs_2Y) to learn more.

 
 

-## NOTE: This is an early pre-release
+---

 
 

-*Black* can already successfully format itself and the standard library.
-It also sports a decent test suite.  However, it is still very new.
-Things will probably be wonky for a while. This is made explicit by the
-"Alpha" trove classifier, as well as by the "a" in the version number.
-What this means for you is that **until the formatter becomes stable,
-you should expect some formatting to change in the future**.
+**[Read the documentation on ReadTheDocs!](https://black.readthedocs.io/en/stable)**

 
 

-Also, as a temporary safety measure, *Black* will check that the
-reformatted code still produces a valid AST that is equivalent to the
-original.  This slows it down.  If you're feeling confident, use
-``--fast``.
+---

 
 

+## Installation and usage

 
 

-## Usage
+### Installation

 
 

-*Black* can be installed by running `pip install black`.
+_Black_ can be installed by running `pip install black`. It requires Python 3.6.2+ to
+run. If you want to format Python 2 code as well, install with
+`pip install black[python2]`. If you want to format Jupyter Notebooks, install with
+`pip install black[jupyter]`.

 
 

-```
-black [OPTIONS] [SRC]...
-
-Options:
-  -l, --line-length INTEGER   Where to wrap around.  [default: 88]
-  --check                     Don't write back the files, just return the
-                              status.  Return code 0 means nothing changed.
-                              Return code 1 means some files were reformatted.
-                              Return code 123 means there was an internal
-                              error.
-  --fast / --safe             If --fast given, skip temporary sanity checks.
-                              [default: --safe]
-  --version                   Show the version and exit.
-  --help                      Show this message and exit.
-```
+If you can't wait for the latest _hotness_ and want to install from GitHub, use:

 
 

+`pip install git+git://github.com/psf/black`

 
 

-## The philosophy behind *Black*
+### Usage

 
 

-*Black* reformats entire files in place.  It is not configurable.  It
-doesn't take previous formatting into account.  It doesn't reformat
-blocks that start with `# fmt: off` and end with `# fmt: on`.  It also
-recognizes [YAPF](https://github.com/google/yapf)'s block comments to
-the same effect, as a courtesy for straddling code.
+To get started right away with sensible defaults:

 
 

+```sh
+black {source_file_or_directory}
+```

 
 

-### How *Black* formats files
+You can run _Black_ as a package if running it as a script doesn't work:

 
 

-*Black* ignores previous formatting and applies uniform horizontal
-and vertical whitespace to your code.  The rules for horizontal
-whitespace are pretty obvious and can be summarized as: do whatever
-makes `pycodestyle` happy.
+```sh
+python -m black {source_file_or_directory}
+```

 
 

-As for vertical whitespace, *Black* tries to render one full expression
-or simple statement per line.  If this fits the allotted line length,
-great.
-```py3
-# in:
-l = [1,
-     2,
-     3,
-]
+Further information can be found in our docs:

 
 

-# out:
-l = [1, 2, 3]
-```
+- [Usage and Configuration](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)

 
 

-If not, *Black* will look at the contents of the first outer matching
-brackets and put that in a separate indented line.
-```py3
-# in:
-l = [[n for n in list_bosses()], [n for n in list_employees()]]
+### NOTE: This is a beta product

 
 

-# out:
-l = [
-    [n for n in list_bosses()], [n for n in list_employees()]
-]
-```
+_Black_ is already [successfully used](https://github.com/psf/black#used-by) by many
+projects, small and big. Black has a comprehensive test suite, with efficient parallel
+tests, and our own auto formatting and parallel Continuous Integration runner. However,
+_Black_ is still beta. Things will probably be wonky for a while. This is made explicit
+by the "Beta" trove classifier, as well as by the "b" in the version number. What this
+means for you is that **until the formatter becomes stable, you should expect some
+formatting to change in the future**. That being said, no drastic stylistic changes are
+planned, mostly responses to bug reports.

 
 

-If that still doesn't fit the bill, it will decompose the internal
-expression further using the same rule, indenting matching brackets
-every time.  If the contents of the matching brackets pair are
-comma-separated (like an argument list, or a dict literal, and so on)
-then *Black* will first try to keep them on the same line with the
-matching brackets.  If that doesn't work, it will put all of them in
-separate lines.
-```py3
-# in:
-def very_important_function(template: str, *variables, *, file: os.PathLike, debug: bool = False):
-    """Applies `variables` to the `template` and writes to `file`."""
-    with open(file, 'w') as f:
-        ...
-
-# out:
-def very_important_function(
-    template: str,
-    *variables,
-    *,
-    file: os.PathLike,
-    debug: bool = False,
-):
-    """Applies `variables` to the `template` and writes to `file`."""
-    with open(file, 'w') as f:
-        ...
-```
+Also, as a safety measure which slows down processing, _Black_ will check that the
+reformatted code still produces a valid AST that is effectively equivalent to the
+original (see the
+[Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#ast-before-and-after-formatting)
+section for details). If you're feeling confident, use `--fast`.

 
 

-You might have noticed that closing brackets are always dedented and
-that a trailing comma is always added.  Such formatting produces smaller
-diffs; when you add or remove an element, it's always just one line.
-Also, having the closing bracket dedented provides a clear delimiter
-between two distinct sections of the code that otherwise share the same
-indentation level (like the arguments list and the docstring in the
-example above).
-
-Unnecessary trailing commas are removed if an expression fits in one
-line.  This makes it 1% more likely that your line won't exceed the
-allotted line length limit.
-
-*Black* avoids spurious vertical whitespace.  This is in the spirit of
-PEP 8 which says that in-function vertical whitespace should only be
-used sparingly.  One exception is control flow statements: *Black* will
-always emit an extra empty line after ``return``, ``raise``, ``break``,
-``continue``, and ``yield``.  This is to make changes in control flow
-more prominent to readers of your code.
-
-That's it.  The rest of the whitespace formatting rules follow PEP 8 and
-are designed to keep `pycodestyle` quiet.
-
-
-### Line length
-
-You probably noticed the peculiar default line length.  *Black* defaults
-to 88 characters per line, which happens to be 10% over 80.  This number
-was found to produce significantly shorter files than sticking with 80
-(the most popular), or even 79 (used by the standard library).  In
-general, [90-ish seems like the wise choice](https://youtu.be/wf-BqAjZb8M?t=260).
-
-If you're paid by the line of code you write, you can pass
-`--line-length` with a lower number.  *Black* will try to respect that.
-However, sometimes it won't be able to without breaking other rules.  In
-those rare cases, auto-formatted code will exceed your allotted limit.
-
-You can also increase it, but remember that people with sight disabilities
-find it harder to work with line lengths exceeding 100 characters.
-It also adversely affects side-by-side diff review  on typical screen
-resolutions.  Long lines also make it harder to present code neatly
-in documentation or talk slides.
-
-If you're using Flake8, you can bump `max-line-length` to 88 and forget
-about it.  Alternatively, use [Bugbear](https://github.com/PyCQA/flake8-bugbear)'s
-B950 warning instead of E501 and keep the max line length at 80 which
-you are probably already using.  You'd do it like this:
-```ini
-[flake8]
-max-line-length = 80
-...
-select = C,E,F,W,B,B950
-ignore = E501
-```
+## The _Black_ code style

 
 

-You'll find *Black*'s own .flake8 config file is configured like this.
-If you're curious about the reasoning behind B950, Bugbear's documentation
-explains it.  The tl;dr is "it's like highway speed limits, we won't
-bother you if you overdo it by a few km/h".
+_Black_ is a PEP 8 compliant opinionated formatter. _Black_ reformats entire files in
+place. Style configuration options are deliberately limited and rarely added. It doesn't
+take previous formatting into account (see [Pragmatism](#pragmatism) for exceptions).

 
 

+Our documentation covers the current _Black_ code style, but planned changes to it are
+also documented. They're both worth taking a look:

 
 

-### Editor integration
+- [The _Black_ Code Style: Current style](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html)
+- [The _Black_ Code Style: Future style](https://black.readthedocs.io/en/stable/the_black_code_style/future_style.html)

 
 

-There is currently no integration with any text editors. Vim and
-Atom/Nuclide integration is planned by the author, others will require
-external contributions.
+Please refer to this document before submitting an issue. What seems like a bug might be
+intended behaviour.

 
 

-Patches welcome! ✨ 🍰 ✨
+### Pragmatism

 
 

+Early versions of _Black_ used to be absolutist in some respects. They took after its
+initial author. This was fine at the time as it made the implementation simpler and
+there were not many users anyway. Not many edge cases were reported. As a mature tool,
+_Black_ does make some exceptions to rules it otherwise holds.

 
 

-## Testimonials
+- [The _Black_ code style: Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#pragmatism)

 
 

-**Dusty Phillips**, [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):
+Please refer to this document before submitting an issue just like with the document
+above. What seems like a bug might be intended behaviour.

 
 

-> Black is opinionated so you don't have to be.
+## Configuration

 
 

-**Hynek Schlawack**, [creator of `attrs`](http://www.attrs.org/), core
-developer of Twisted and CPython:
+_Black_ is able to read project-specific default values for its command line options
+from a `pyproject.toml` file. This is especially useful for specifying custom
+`--include` and `--exclude`/`--force-exclude`/`--extend-exclude` patterns for your
+project.

 
 

-> An auto-formatter that doesn't suck is all I want for Xmas!
+You can find more details in our documentation:

 
 

-**Carl Meyer**, [Django](https://www.djangoproject.com/) core developer:
+- [The basics: Configuration via a file](https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-via-a-file)

 
 

-> At least the name is good.
+And if you're looking for more general configuration documentation:

 
 

-**Kenneth Reitz**, creator of [`requests`](http://python-requests.org/)
-and [`pipenv`](https://docs.pipenv.org/):
+- [Usage and Configuration](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)

 
 

-> This vastly improves the formatting of our code. Thanks a ton!
+**Pro-tip**: If you're asking yourself "Do I need to configure anything?" the answer is
+"No". _Black_ is all about sensible defaults. Applying those defaults will have your
+code in compliance with many other _Black_ formatted projects.

 
 

+## Used by

 
 

-## Tests
+The following notable open-source projects trust _Black_ with enforcing a consistent
+code style: pytest, tox, Pyramid, Django Channels, Hypothesis, attrs, SQLAlchemy,
+Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow,
+Twisted, LocalStack, every Datadog Agent Integration, Home Assistant, Zulip, Kedro, and
+many more.

 
 

-Just run:
+The following organizations use _Black_: Facebook, Dropbox, KeepTruckin, Mozilla, Quora,
+Duolingo, QuantumBlack, Tesla.

 
 

-```
-python setup.py test
-```
+Are we missing anyone? Let us know.

 
 

-## This tool requires Python 3.6.0+ to run
+## Testimonials

 
 

-But you can reformat Python 2 code with it, too.  *Black* is able to parse
-all of the new syntax supported on Python 3.6 but also *effectively all*
-the Python 2 syntax at the same time, as long as you're not using print
-statements.
+**Mike Bayer**, [author of `SQLAlchemy`](https://www.sqlalchemy.org/):

 
 

-By making the code exclusively Python 3.6+, I'm able to focus on the
-quality of the formatting and re-use all the nice features of the new
-releases (check out [pathlib](https://docs.python.org/3/library/pathlib.html) or
-f-strings) instead of wasting cycles on Unicode compatibility, and so on.
+> I can't think of any single tool in my entire programming career that has given me a
+> bigger productivity increase by its introduction. I can now do refactorings in about
+> 1% of the keystrokes that it would have taken me previously when we had no way for
+> code to format itself.

 
 

+**Dusty Phillips**,
+[writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):

 
 

-## License
+> _Black_ is opinionated so you don't have to be.

 
 

-MIT
+**Hynek Schlawack**, [creator of `attrs`](https://www.attrs.org/), core developer of
+Twisted and CPython:

 
 

+> An auto-formatter that doesn't suck is all I want for Xmas!

 
 

-## Contributing
+**Carl Meyer**, [Django](https://www.djangoproject.com/) core developer:

 
 

-In terms of inspiration, *Black* is about as configurable as *gofmt* and
-*rustfmt* are.  This is deliberate.
+> At least the name is good.
+
+**Kenneth Reitz**, creator of [`requests`](http://python-requests.org/) and
+[`pipenv`](https://readthedocs.org/projects/pipenv/):
+
+> This vastly improves the formatting of our code. Thanks a ton!

 
 

-Bug reports and fixes are always welcome!  However, before you suggest a
-new feature or configuration knob, ask yourself why you want it.  If it
-enables better integration with some workflow, fixes an inconsistency,
-speeds things up, and so on - go for it!  On the other hand, if your
-answer is "because I don't like a particular formatting" then you're not
-ready to embrace *Black* yet. Such changes are unlikely to get accepted.
-You can still try but prepare to be disappointed.
+## Show your style

 
 

+Use the badge in your project's README.md:

 
 

-## Change Log
+```md
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+```

 
 

-### 18.3a2 (unreleased)
+Using the badge in README.rst:

 
 

-* fixed missing space in numpy-style array indexing (#33)
+```
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/psf/black
+```

 
 

-* fixed spurious space after star-based unary expressions (#31)
+Looks like this:
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

 
 

+## License

 
 

-### 18.3a1
+MIT

 
 

-* added `--check`
+## Contributing

 
 

-* only put trailing commas in function signatures and calls if it's
-  safe to do so. If the file is Python 3.6+ it's always safe, otherwise
-  only safe if there are no `*args` or `**kwargs` used in the signature
-  or call. (#8)
+Welcome! Happy to see you willing to make the project better. You can get started by
+reading this:

 
 

-* fixed invalid spacing of dots in relative imports (#6, #13)
+- [Contributing: The basics](https://black.readthedocs.io/en/latest/contributing/the_basics.html)

 
 

-* fixed invalid splitting after comma on unpacked variables in for-loops
-  (#23)
+You can also take a look at the rest of the contributing docs or talk with the
+developers:

 
 

-* fixed spurious space in parenthesized set expressions (#7)
+- [Contributing documentation](https://black.readthedocs.io/en/latest/contributing/index.html)
+- [Chat on Discord](https://discord.gg/RtVdv86PrH)

 
 

-* fixed spurious space after opening parentheses and in default
-  arguments (#14, #17)
+## Change log

 
 

-* fixed spurious space after unary operators when the operand was
-  a complex expression (#15)
+The log has become rather long. It moved to its own file.

 
 

+See [CHANGES](https://black.readthedocs.io/en/latest/change_log.html).

 
 

-### 18.3a0
+## Authors

 
 

-* first published version, Happy 🍰 Day 2018!
+The author list is quite long nowadays, so it lives in its own file.

 
 

-* alpha quality
+See [AUTHORS.md](./AUTHORS.md)

 
 

-* date-versioned (see: https://calver.org/)
+## Code of Conduct

 
 

+Everyone participating in the _Black_ project, and in particular in the issue tracker,
+pull requests, and social media activity, is expected to treat other people with respect
+and more generally to follow the guidelines articulated in the
+[Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/).

 
 

-## Authors
+At the same time, humor is encouraged. In fact, basic familiarity with Monty Python's
+Flying Circus is expected. We are not savages.

 
 

-Glued together by [Łukasz Langa](mailto:lukasz@langa.pl).
+And if you _really_ need to slap somebody, do it with a fish while dancing.