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     "a key in my dict": a_very_long_variable
  97     * and_a_very_long_function_call()
  98     / 100000.0,
  99     "another key": (short_value),
 100 }
 101 ```
 102
 103 will be changed to:
 104
 105 ```python
 106 my_dict = {
 107     "a key in my dict": (
 108         a_very_long_variable * and_a_very_long_function_call() / 100000.0
 109     ),
 110     "another key": short_value,
 111 }
 112 ```
 113
 114 ### Improved multiline string handling
 115
 116 _Black_ is smarter when formatting multiline strings, especially in function arguments,
 117 to avoid introducing extra line breaks. Previously, it would always consider multiline
 118 strings as not fitting on a single line. With this new feature, _Black_ looks at the
 119 context around the multiline string to decide if it should be inlined or split to a
 120 separate line. For example, when a multiline string is passed to a function, _Black_
 121 will only split the multiline string if a line is too long or if multiple arguments are
 122 being passed.
 123
 124 For example, _Black_ will reformat
 125
 126 ```python
 127 textwrap.dedent(
 128     """\
 129     This is a
 130     multiline string
 131 """
 132 )
 133 ```
 134
 135 to:
 136
 137 ```python
 138 textwrap.dedent("""\
 139     This is a
 140     multiline string
 141 """)
 142 ```
 143
 144 And:
 145
 146 ```python
 147 MULTILINE = """
 148 foobar
 149 """.replace(
 150     "\n", ""
 151 )
 152 ```
 153
 154 to:
 155
 156 ```python
 157 MULTILINE = """
 158 foobar
 159 """.replace("\n", "")
 160 ```