Elaborate on what AST changes Black might perform

[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 19464ba482a083e6d46d3f4db09ce2ec3d4a8c6d..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".


@@ -289,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


@@ -438,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


@@ -446,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.