X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/537ea8df35b1004bdb228b483907fb5dd92e5257..b39999da7f451c285befac217f1f9a685774b34d:/docs/the_black_code_style.md?ds=inline diff --git a/docs/the_black_code_style.md b/docs/the_black_code_style.md index 09d5830..39a452f 100644 --- 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. -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] -max-line-length = 80 +max-line-length = 88 ... select = C,E,F,W,B,B950 -ignore = E203, E501, W503 +extend-ignore = E203, E501 ``` -You'll find _Black_'s own .flake8 config file is configured like this. Explanation of -why W503 and E203 are 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". @@ -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. -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. @@ -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. +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 @@ -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. +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 @@ -309,10 +318,6 @@ multiple lines. This is so that _Black_ is compliant with the recent changes in [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 @@ -448,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. +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 @@ -456,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. + +### 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.