Use pre-commit/action to simplify CI (#2191)

[etc/vim.git] / docs / the_black_code_style.md

diff --git a/docs/the_black_code_style.md b/docs/the_black_code_style.md
index 735e9c015d70d468a723a5e6d361ed766b096c43..39a452ff9a81d74abf20ce88e962e579e7a9cfae 100644 (file)
--- a/docs/the_black_code_style.md
+++ b/docs/the_black_code_style.md
@@ -189,22 +189,22 @@ harder to work with line lengths exceeding 100 characters. It also adversely aff
 side-by-side diff review on typical screen resolutions. Long lines also make it harder
 to present code neatly in documentation or talk slides.
 
 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:
+If you're using Flake8, you can bump `max-line-length` to 88 and mostly forget about it.
+However, it's better if you use [Bugbear](https://github.com/PyCQA/flake8-bugbear)'s
+B950 warning instead of E501, and bump the max line length to 88 (or the `--line-length`
+you used for black), which will align more with black's _"try to respect
+`--line-length`, but don't become crazy if you can't"_. You'd do it like this:

 
 ```ini
 [flake8]
 
 ```ini
 [flake8]

-max-line-length = 80
+max-line-length = 88

 ...
 select = C,E,F,W,B,B950
 extend-ignore = E203, E501
 ```
 
 ...
 select = C,E,F,W,B,B950
 extend-ignore = E203, E501
 ```
 

-You'll find _Black_'s own .flake8 config file is configured like this. Explanation of
-why E203 is disabled can be found further in this documentation. And if you're curious
-about the reasoning behind B950,
+Explanation of why E203 is disabled can be found further in this documentation. And if
+you're curious about the reasoning behind B950,

 [Bugbear's documentation](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings)
 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".
 [Bugbear's documentation](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings)
 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".


@@ -244,16 +244,6 @@ required due to an inner function starting immediately after.
 _Black_ will add trailing commas to expressions that are split by comma where each
 element is on its own line. This includes function signatures.
 
 _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.
 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.


@@ -262,6 +252,10 @@ in function signatures that have stars in them. In other words, if you'd like a
 comma in this situation and _Black_ didn't recognize it was safe to do so, put it there
 manually and _Black_ will keep it.
 
 comma in this situation and _Black_ didn't recognize it was safe to do so, put it there
 manually and _Black_ will keep it.
 

+A pre-existing trailing comma informs _Black_ to always explode contents of the current
+bracket pair into one item per line. Read more about this in the
+[Pragmatism](#pragmatism) section below.
+

 ### Strings
 
 _Black_ prefers double quotes (`"` and `"""`) over single quotes (`'` and `'''`). It
 ### Strings
 
 _Black_ prefers double quotes (`"` and `"""`) over single quotes (`'` and `'''`). It


@@ -295,6 +289,21 @@ If you are adopting _Black_ in a large project with pre-existing string conventi
 you can pass `--skip-string-normalization` on the command line. This is meant as an
 adoption helper, avoid using this for new projects.
 
 you can pass `--skip-string-normalization` on the command line. This is meant as an
 adoption helper, avoid using this for new projects.
 

+As an experimental option, _Black_ splits long strings (using parentheses where
+appropriate) and merges short ones. When split, parts of f-strings that don't need
+formatting are converted to plain strings. User-made splits are respected when they do
+not exceed the line length limit. Line continuation backslashes are converted into
+parenthesized strings. Unnecessary parentheses are stripped. To enable experimental
+string processing, pass `--experimental-string-processing` on the command line. Because
+the functionality is experimental, feedback and issue reports are highly encouraged!
+
+_Black_ also processes docstrings. Firstly the indentation of docstrings is corrected
+for both quotations and the text within, although relative indentation in the text is
+preserved. Superfluous trailing whitespace on each line and unnecessary new lines at the
+end of the docstring are removed. All leading tabs are converted to spaces, but tabs
+inside text are preserved. Whitespace leading and trailing one-line docstrings is
+removed. The quotations of an empty docstring are separated with one space.
+

 ### Numeric literals
 
 _Black_ standardizes most numeric literals to use lowercase letters for the syntactic
 ### Numeric literals
 
 _Black_ standardizes most numeric literals to use lowercase letters for the syntactic


@@ -444,6 +453,9 @@ into one item per line.
 How do you make it stop? Just delete that trailing comma and _Black_ will collapse your
 collection into one line if it fits.
 
 How do you make it stop? Just delete that trailing comma and _Black_ will collapse your
 collection into one line if it fits.
 

+If you must, you can recover the behaviour of early versions of Black with the option
+`--skip-magic-trailing-comma` / `-C`.
+

 ### r"strings" and R"strings"
 
 _Black_ normalizes string quotes as well as string prefixes, making them lowercase. One
 ### r"strings" and R"strings"
 
 _Black_ normalizes string quotes as well as string prefixes, making them lowercase. One


@@ -452,3 +464,32 @@ exception to this rule is r-strings. It turns out that the very popular
 default by (among others) GitHub and Visual Studio Code, differentiates between
 r-strings and R-strings. The former are syntax highlighted as regular expressions while
 the latter are treated as true raw strings with no special semantics.
 default by (among others) GitHub and Visual Studio Code, differentiates between
 r-strings and R-strings. The former are syntax highlighted as regular expressions while
 the latter are treated as true raw strings with no special semantics.

+
+### AST before and after formatting
+
+When run with `--safe`, _Black_ checks that the code before and after is semantically
+equivalent. This check is done by comparing the AST of the source with the AST of the
+target. There are three limited cases in which the AST does differ:
+
+1. _Black_ cleans up leading and trailing whitespace of docstrings, re-indenting them if
+   needed. It's been one of the most popular user-reported features for the formatter to
+   fix whitespace issues with docstrings. While the result is technically an AST
+   difference, due to the various possibilities of forming docstrings, all realtime use
+   of docstrings that we're aware of sanitizes indentation and leading/trailing
+   whitespace anyway.
+
+2. _Black_ manages optional parentheses for some statements. In the case of the `del`
+   statement, presence of wrapping parentheses or lack of thereof changes the resulting
+   AST but is semantically equivalent in the interpreter.
+
+3. _Black_ might move comments around, which includes type comments. Those are part of
+   the AST as of Python 3.8. While the tool implements a number of special cases for
+   those comments, there is no guarantee they will remain where they were in the source.
+   Note that this doesn't change runtime behavior of the source code.
+
+To put things in perspective, the code equivalence check is a feature of _Black_ which
+other formatters don't implement at all. It is of crucial importance to us to ensure
+code behaves the way it did before it got reformatted. We treat this as a feature and
+there are no plans to relax this in the future. The exceptions enumerated above stem
+from either user feedback or implementation details of the tool. In each case we made
+due diligence to ensure that the AST divergence is of no practical consequence.