.vim/bundle/black/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 (labels/preview-style)=
  51
  52 ## Preview style
  53
  54 Experimental, potentially disruptive style changes are gathered under the `--preview`
  55 CLI flag. At the end of each year, these changes may be adopted into the default style,
  56 as described in [The Black Code Style](index.md). Because the functionality is
  57 experimental, feedback and issue reports are highly encouraged!
  58
  59 ### Improved string processing
  60
  61 _Black_ will split long string literals and merge short ones. Parentheses are used where
  62 appropriate. When split, parts of f-strings that don't need formatting are converted to
  63 plain strings. User-made splits are respected when they do not exceed the line length
  64 limit. Line continuation backslashes are converted into parenthesized strings.
  65 Unnecessary parentheses are stripped. The stability and status of this feature is
  66 tracked in [this issue](https://github.com/psf/black/issues/2188).
  67
  68 ### Improved line breaks
  69
  70 For assignment expressions, _Black_ now prefers to split and wrap the right side of the
  71 assignment instead of left side. For example:
  72
  73 ```python
  74 some_dict[
  75     "with_a_long_key"
  76 ] = some_looooooooong_module.some_looooooooooooooong_function_name(
  77     first_argument, second_argument, third_argument
  78 )
  79 ```
  80
  81 will be changed to:
  82
  83 ```python
  84 some_dict["with_a_long_key"] = (
  85     some_looooooooong_module.some_looooooooooooooong_function_name(
  86         first_argument, second_argument, third_argument
  87     )
  88 )
  89 ```
  90
  91 ### Improved parentheses management
  92
  93 For dict literals with long values, they are now wrapped in parentheses. Unnecessary
  94 parentheses are now removed. For example:
  95
  96 ```python
  97 my_dict = {
  98     "a key in my dict": a_very_long_variable
  99     * and_a_very_long_function_call()
 100     / 100000.0,
 101     "another key": (short_value),
 102 }
 103 ```
 104
 105 will be changed to:
 106
 107 ```python
 108 my_dict = {
 109     "a key in my dict": (
 110         a_very_long_variable * and_a_very_long_function_call() / 100000.0
 111     ),
 112     "another key": short_value,
 113 }
 114 ```
 115
 116 ### Improved multiline string handling
 117
 118 _Black_ is smarter when formatting multiline strings, especially in function arguments,
 119 to avoid introducing extra line breaks. Previously, it would always consider multiline
 120 strings as not fitting on a single line. With this new feature, _Black_ looks at the
 121 context around the multiline string to decide if it should be inlined or split to a
 122 separate line. For example, when a multiline string is passed to a function, _Black_
 123 will only split the multiline string if a line is too long or if multiple arguments are
 124 being passed.
 125
 126 For example, _Black_ will reformat
 127
 128 ```python
 129 textwrap.dedent(
 130     """\
 131     This is a
 132     multiline string
 133 """
 134 )
 135 ```
 136
 137 to:
 138
 139 ```python
 140 textwrap.dedent("""\
 141     This is a
 142     multiline string
 143 """)
 144 ```
 145
 146 And:
 147
 148 ```python
 149 MULTILINE = """
 150 foobar
 151 """.replace(
 152     "\n", ""
 153 )
 154 ```
 155
 156 to:
 157
 158 ```python
 159 MULTILINE = """
 160 foobar
 161 """.replace("\n", "")
 162 ```
 163
 164 Implicit multiline strings are special, because they can have inline comments. Strings
 165 without comments are merged, for example
 166
 167 ```python
 168 s = (
 169     "An "
 170     "implicit "
 171     "multiline "
 172     "string"
 173 )
 174 ```
 175
 176 becomes
 177
 178 ```python
 179 s = "An implicit multiline string"
 180 ```
 181
 182 A comment on any line of the string (or between two string lines) will block the
 183 merging, so
 184
 185 ```python
 186 s = (
 187     "An "  # Important comment concerning just this line
 188     "implicit "
 189     "multiline "
 190     "string"
 191 )
 192 ```
 193
 194 and
 195
 196 ```python
 197 s = (
 198     "An "
 199     "implicit "
 200     # Comment in between
 201     "multiline "
 202     "string"
 203 )
 204 ```
 205
 206 will not be merged. Having the comment after or before the string lines (but still
 207 inside the parens) will merge the string. For example
 208
 209 ```python
 210 s = (  # Top comment
 211     "An "
 212     "implicit "
 213     "multiline "
 214     "string"
 215     # Bottom comment
 216 )
 217 ```
 218
 219 becomes
 220
 221 ```python
 222 s = (  # Top comment
 223     "An implicit multiline string"
 224     # Bottom comment
 225 )
 226 ```