-_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.
-
-_Black_ will allow single empty lines inside functions, and single and double empty
-lines on module level left by the original editors, except when they're within
-parenthesized expressions. Since such expressions are always reformatted to fit minimal
-space, this whitespace is lost.
-
-It will also insert proper spacing before and after function definitions. It's one line
-before and after inner functions and two lines before and after module-level functions
-and classes. _Black_ will not put empty lines between function/class definitions and
-standalone comments that immediately precede the given function/class.
-
-_Black_ will enforce single empty lines between a class-level docstring and the first
-following field or method. This conforms to
-[PEP 257](https://www.python.org/dev/peps/pep-0257/#multi-line-docstrings).
-
-_Black_ won't insert empty lines after function docstrings unless that empty line is
-required due to an inner function starting immediately after.
-
-### Trailing commas
-
-_Black_ will add trailing commas to expressions that are split by comma where each
-element is on its own line. This includes function signatures.
-
-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. Moreover, in
-this scenario, if you added another argument to your call, you'd probably fit it in the
-same line anyway. That doesn't make diffs any larger.
-
-One exception to removing trailing commas is tuple expressions with just one element. In
-this case _Black_ won't touch the single trailing comma as this would unexpectedly
-change the underlying data type. Note that this is also the case when commas are used
-while indexing. This is a tuple in disguise: `numpy_array[3, ]`.
-
-One exception to adding trailing commas is function signatures containing `*`, `*args`,
-or `**kwargs`. In this case a trailing comma is only safe to use on Python 3.6. _Black_
-will detect if your file is already 3.6+ only and use trailing commas in this situation.
-If you wonder how it knows, it looks for f-strings and existing use of trailing commas
-in function signatures that have stars in them. In other words, if you'd like a trailing
-comma in this situation and _Black_ didn't recognize it was safe to do so, put it there
-manually and _Black_ will keep it.
-
-### Strings
-
-_Black_ prefers double quotes (`"` and `"""`) over single quotes (`'` and `'''`). It
-will replace the latter with the former as long as it does not result in more backslash
-escapes than before.
-
-_Black_ also standardizes string prefixes, making them always lowercase. On top of that,
-if your code is already Python 3.6+ only or it's using the `unicode_literals` future
-import, _Black_ will remove `u` from the string prefix as it is meaningless in those
-scenarios.
-
-The main reason to standardize on a single form of quotes is aesthetics. Having one kind
-of quotes everywhere reduces reader distraction. It will also enable a future version of
-_Black_ to merge consecutive string literals that ended up on the same line (see
-[#26](https://github.com/psf/black/issues/26) for details).
-
-Why settle on double quotes? They anticipate apostrophes in English text. They match the
-docstring standard described in
-[PEP 257](https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring). An empty
-string in double quotes (`""`) is impossible to confuse with a one double-quote
-regardless of fonts and syntax highlighting used. On top of this, double quotes for
-strings are consistent with C which Python interacts a lot with.
-
-On certain keyboard layouts like US English, typing single quotes is a bit easier than
-double quotes. The latter requires use of the Shift key. My recommendation here is to
-keep using whatever is faster to type and let _Black_ handle the transformation.
-
-If you are adopting _Black_ in a large project with pre-existing string conventions
-(like the popular
-["single quotes for data, double quotes for human-readable strings"](https://stackoverflow.com/a/56190)),
-you can pass `--skip-string-normalization` on the command line. This is meant as an
-adoption helper, avoid using this for new projects.
-
-### Numeric literals
-
-_Black_ standardizes most numeric literals to use lowercase letters for the syntactic
-parts and uppercase letters for the digits themselves: `0xAB` instead of `0XAB` and
-`1e10` instead of `1E10`. Python 2 long literals are styled as `2L` instead of `2l` to
-avoid confusion between `l` and `1`.
-
-### Line breaks & binary operators
-
-_Black_ will break a line before a binary operator when splitting a block of code over
-multiple lines. This is so that _Black_ is compliant with the recent changes in the
-[PEP 8](https://www.python.org/dev/peps/pep-0008/#should-a-line-break-before-or-after-a-binary-operator)
-style guide, which emphasizes that this approach improves readability.
-
-This behaviour may raise `W503 line break before binary operator` warnings in style
-guide enforcement tools like Flake8. Since `W503` is not PEP 8 compliant, you should
-tell Flake8 to ignore these warnings.
-
-### Slices
-
-PEP 8
-[recommends](https://www.python.org/dev/peps/pep-0008/#whitespace-in-expressions-and-statements)
-to treat `:` in slices as a binary operator with the lowest priority, and to leave an
-equal amount of space on either side, except if a parameter is omitted (e.g.
-`ham[1 + 1 :]`). It recommends no spaces around `:` operators for "simple expressions"
-(`ham[lower:upper]`), and extra space for "complex expressions"
-(`ham[lower : upper + offset]`). _Black_ treats anything more than variable names as
-"complex" (`ham[lower : upper + 1]`). It also states that for extended slices, both `:`
-operators have to have the same amount of spacing, except if a parameter is omitted
-(`ham[1 + 1 ::]`). _Black_ enforces these rules consistently.
-
-This behaviour may raise `E203 whitespace before ':'` warnings in style guide
-enforcement tools like Flake8. Since `E203` is not PEP 8 compliant, you should tell
-Flake8 to ignore these warnings.
-
-### Parentheses
-
-Some parentheses are optional in the Python grammar. Any expression can be wrapped in a
-pair of parentheses to form an atom. There are a few interesting cases:
-
-- `if (...):`
-- `while (...):`
-- `for (...) in (...):`
-- `assert (...), (...)`
-- `from X import (...)`
-- assignments like:
- - `target = (...)`
- - `target: type = (...)`
- - `some, *un, packing = (...)`
- - `augmented += (...)`
-
-In those cases, parentheses are removed when the entire statement fits in one line, or
-if the inner expression doesn't have any delimiters to further split on. If there is
-only a single delimiter and the expression starts or ends with a bracket, the
-parenthesis can also be successfully omitted since the existing bracket pair will
-organize the expression neatly anyway. Otherwise, the parentheses are added.
-
-Please note that _Black_ does not add or remove any additional nested parentheses that
-you might want to have for clarity or further code organization. For example those
-parentheses are not going to be removed:
-
-```py3
-return not (this or that)
-decision = (maybe.this() and values > 0) or (maybe.that() and values < 0)
-```
-
-### Call chains
-
-Some popular APIs, like ORMs, use call chaining. This API style is known as a
-[fluent interface](https://en.wikipedia.org/wiki/Fluent_interface). _Black_ formats
-those by treating dots that follow a call or an indexing operation like a very low
-priority delimiter. It's easier to show the behavior than to explain it. Look at the
-example:
-
-```py3
-def example(session):
- result = (
- session.query(models.Customer.id)
- .filter(
- models.Customer.account_id == account_id,
- models.Customer.email == email_address,
- )
- .order_by(models.Customer.id.asc())
- .all()
- )
-```
-
-### Typing stub files
-
-PEP 484 describes the syntax for type hints in Python. One of the use cases for typing
-is providing type annotations for modules which cannot contain them directly (they might
-be written in C, or they might be third-party, or their implementation may be overly
-dynamic, and so on).
-
-To solve this,
-[stub files with the `.pyi` file extension](https://www.python.org/dev/peps/pep-0484/#stub-files)
-can be used to describe typing information for an external module. Those stub files omit
-the implementation of classes and functions they describe, instead they only contain the
-structure of the file (listing globals, functions, and classes with their members). The
-recommended code style for those files is more terse than PEP 8:
-
-- prefer `...` on the same line as the class/function signature;
-- avoid vertical whitespace between consecutive module-level functions, names, or
- methods and fields within a single class;
-- use a single blank line between top-level class definitions, or none if the classes
- are very small.
-
-_Black_ enforces the above rules. There are additional guidelines for formatting `.pyi`
-file that are not enforced yet but might be in a future version of the formatter:
-
-- all function bodies should be empty (contain `...` instead of the body);
-- do not use docstrings;
-- prefer `...` over `pass`;
-- for arguments with a default, use `...` instead of the actual default;
-- avoid using string literals in type annotations, stub files support forward references
- natively (like Python 3.7 code with `from __future__ import annotations`);
-- use variable annotations instead of type comments, even for stubs that target older
- versions of Python;
-- for arguments that default to `None`, use `Optional[]` explicitly;
-- use `float` instead of `Union[int, float]`.
projects / etc / vim.git / blobdiff