]> 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:

Specify Python exec path with minor version if available (#3508)
[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, when we implement this, 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_ uses parentheses
35 instead in `--preview` mode (see below) 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.md). 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 line breaks
67
68 For assignment expressions, _Black_ now prefers to split and wrap the right side of the
69 assignment instead of left side. For example:
70
71 ```python
72 some_dict[
73     "with_a_long_key"
74 ] = some_looooooooong_module.some_looooooooooooooong_function_name(
75     first_argument, second_argument, third_argument
76 )
77 ```
78
79 will be changed to:
80
81 ```python
82 some_dict["with_a_long_key"] = (
83     some_looooooooong_module.some_looooooooooooooong_function_name(
84         first_argument, second_argument, third_argument
85     )
86 )
87 ```
88
89 ### Improved parentheses management
90
91 For dict literals with long values, they are now wrapped in parentheses. Unnecessary
92 parentheses are now removed. For example:
93
94 ```python
95 my_dict = {
96     my_dict = {
97     "a key in my dict": a_very_long_variable
98     * and_a_very_long_function_call()
99     / 100000.0,
100     "another key": (short_value),
101 }
102 ```
103
104 will be changed to:
105
106 ```python
107 my_dict = {
108     "a key in my dict": (
109         a_very_long_variable * and_a_very_long_function_call() / 100000.0
110     ),
111     "another key": short_value,
112 }
113 ```
114
115 ### Improved multiline string handling
116
117 _Black_ is smarter when formatting multiline strings, especially in function arguments,
118 to avoid introducing extra line breaks. Previously, it would always consider multiline
119 strings as not fitting on a single line. With this new feature, _Black_ looks at the
120 context around the multiline string to decide if it should be inlined or split to a
121 separate line. For example, when a multiline string is passed to a function, _Black_
122 will only split the multiline string if a line is too long or if multiple arguments are
123 being passed.
124
125 For example, _Black_ will reformat
126
127 ```python
128 textwrap.dedent(
129     """\
130     This is a
131     multiline string
132 """
133 )
134 ```
135
136 to:
137
138 ```python
139 textwrap.dedent("""\
140     This is a
141     multiline string
142 """)
143 ```
144
145 And:
146
147 ```python
148 MULTILINE = """
149 foobar
150 """.replace(
151     "\n", ""
152 )
153 ```
154
155 to:
156
157 ```python
158 MULTILINE = """
159 foobar
160 """.replace("\n", "")
161 ```