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_manager(1) as cm1, \
  27      make_context_manager(2) as cm2, \
  28      make_context_manager(3) as cm3, \
  29      make_context_manager(4) 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 ## Preview style
  38
  39 Experimental, potentially disruptive style changes are gathered under the `--preview`
  40 CLI flag. At the end of each year, these changes may be adopted into the default style,
  41 as described in [The Black Code Style](./index.rst). Because the functionality is
  42 experimental, feedback and issue reports are highly encouraged!
  43
  44 ### Improved string processing
  45
  46 _Black_ will split long string literals and merge short ones. Parentheses are used where
  47 appropriate. When split, parts of f-strings that don't need formatting are converted to
  48 plain strings. User-made splits are respected when they do not exceed the line length
  49 limit. Line continuation backslashes are converted into parenthesized strings.
  50 Unnecessary parentheses are stripped. The stability and status of this feature is
  51 tracked in [this issue](https://github.com/psf/black/issues/2188).
  52
  53 ### Removing newlines in the beginning of code blocks
  54
  55 _Black_ will remove newlines in the beginning of new code blocks, i.e. when the
  56 indentation level is increased. For example:
  57
  58 ```python
  59 def my_func():
  60
  61     print("The line above me will be deleted!")
  62 ```
  63
  64 will be changed to:
  65
  66 ```python
  67 def my_func():
  68     print("The line above me will be deleted!")
  69 ```
  70
  71 This new feature will be applied to **all code blocks**: `def`, `class`, `if`, `for`,
  72 `while`, `with`, `case` and `match`.
  73
  74 ### Improved parentheses management
  75
  76 _Black_ will format parentheses around return annotations similarly to other sets of
  77 parentheses. For example:
  78
  79 ```python
  80 def foo() -> (int):
  81     ...
  82
  83 def foo() -> looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong:
  84     ...
  85 ```
  86
  87 will be changed to:
  88
  89 ```python
  90 def foo() -> int:
  91     ...
  92
  93
  94 def foo() -> (
  95     looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong
  96 ):
  97     ...
  98 ```
  99
 100 And, extra parentheses in `await` expressions and `with` statements are removed. For
 101 example:
 102
 103 ```python
 104 with ((open("bla.txt")) as f, open("x")):
 105     ...
 106
 107 async def main():
 108     await (asyncio.sleep(1))
 109 ```
 110
 111 will be changed to:
 112
 113 ```python
 114 with open("bla.txt") as f, open("x"):
 115     ...
 116
 117
 118 async def main():
 119     await asyncio.sleep(1)
 120 ```