]> git.madduck.net Git - etc/vim.git/blob - docs/the_black_code_style/future_style.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Vim plugin: allow using system black rather than virtualenv (#3309)
[etc/vim.git] / docs / the_black_code_style / future_style.md
1 # The (future of the) Black code style
2
3 ```{warning}
4 Changes to this document often aren't tied and don't relate to releases of
5 _Black_. It's recommended that you read the latest version available.
6 ```
7
8 ## Using backslashes for with statements
9
10 [Backslashes are bad and should be never be used](labels/why-no-backslashes) however
11 there is one exception: `with` statements using multiple context managers. Before Python
12 3.9 Python's grammar does not allow organizing parentheses around the series of context
13 managers.
14
15 We don't want formatting like:
16
17 ```py3
18 with make_context_manager1() as cm1, make_context_manager2() as cm2, make_context_manager3() as cm3, make_context_manager4() as cm4:
19     ...  # nothing to split on - line too long
20 ```
21
22 So _Black_ will eventually format it like this:
23
24 ```py3
25 with \
26      make_context_manager1() as cm1, \
27      make_context_manager2() as cm2, \
28      make_context_manager3() as cm3, \
29      make_context_manager4() as cm4 \
30 :
31     ...  # backslashes and an ugly stranded colon
32 ```
33
34 Although when the target version is Python 3.9 or higher, _Black_ will use parentheses
35 instead since they're allowed in Python 3.9 and higher.
36
37 An alternative to consider if the backslashes in the above formatting are undesirable is
38 to use {external:py:obj}`contextlib.ExitStack` to combine context managers in the
39 following way:
40
41 ```python
42 with contextlib.ExitStack() as exit_stack:
43     cm1 = exit_stack.enter_context(make_context_manager1())
44     cm2 = exit_stack.enter_context(make_context_manager2())
45     cm3 = exit_stack.enter_context(make_context_manager3())
46     cm4 = exit_stack.enter_context(make_context_manager4())
47     ...
48 ```
49
50 ## Preview style
51
52 Experimental, potentially disruptive style changes are gathered under the `--preview`
53 CLI flag. At the end of each year, these changes may be adopted into the default style,
54 as described in [The Black Code Style](./index.rst). Because the functionality is
55 experimental, feedback and issue reports are highly encouraged!
56
57 ### Improved string processing
58
59 _Black_ will split long string literals and merge short ones. Parentheses are used where
60 appropriate. When split, parts of f-strings that don't need formatting are converted to
61 plain strings. User-made splits are respected when they do not exceed the line length
62 limit. Line continuation backslashes are converted into parenthesized strings.
63 Unnecessary parentheses are stripped. The stability and status of this feature is
64 tracked in [this issue](https://github.com/psf/black/issues/2188).
65
66 ### Improved empty line management
67
68 1.  _Black_ will remove newlines in the beginning of new code blocks, i.e. when the
69     indentation level is increased. For example:
70
71     ```python
72     def my_func():
73
74         print("The line above me will be deleted!")
75     ```
76
77     will be changed to:
78
79     ```python
80     def my_func():
81         print("The line above me will be deleted!")
82     ```
83
84     This new feature will be applied to **all code blocks**: `def`, `class`, `if`,
85     `for`, `while`, `with`, `case` and `match`.
86
87 2.  _Black_ will enforce empty lines before classes and functions with leading comments.
88     For example:
89
90     ```python
91     some_var = 1
92     # Leading sticky comment
93     def my_func():
94         ...
95     ```
96
97     will be changed to:
98
99     ```python
100     some_var = 1
101
102
103     # Leading sticky comment
104     def my_func():
105         ...
106     ```
107
108 ### Improved parentheses management
109
110 _Black_ will format parentheses around return annotations similarly to other sets of
111 parentheses. For example:
112
113 ```python
114 def foo() -> (int):
115     ...
116
117 def foo() -> looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong:
118     ...
119 ```
120
121 will be changed to:
122
123 ```python
124 def foo() -> int:
125     ...
126
127
128 def foo() -> (
129     looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong
130 ):
131     ...
132 ```
133
134 And, extra parentheses in `await` expressions and `with` statements are removed. For
135 example:
136
137 ```python
138 with ((open("bla.txt")) as f, open("x")):
139     ...
140
141 async def main():
142     await (asyncio.sleep(1))
143 ```
144
145 will be changed to:
146
147 ```python
148 with open("bla.txt") as f, open("x"):
149     ...
150
151
152 async def main():
153     await asyncio.sleep(1)
154 ```