docs/the_black_code_style/index.md

   1 # The Black Code Style
   2
   3 ```{toctree}
   4 ---
   5 hidden:
   6 ---
   7
   8 Current style <current_style>
   9 Future style <future_style>
  10 ```
  11
  12 _Black_ is a PEP 8 compliant opinionated formatter with its own style.
  13
  14 While keeping the style unchanged throughout releases has always been a goal, the
  15 _Black_ code style isn't set in stone. It evolves to accommodate for new features in the
  16 Python language and, occasionally, in response to user feedback. Large-scale style
  17 preferences presented in {doc}`current_style` are very unlikely to change, but minor
  18 style aspects and details might change according to the stability policy presented
  19 below. Ongoing style considerations are tracked on GitHub with the
  20 [design](https://github.com/psf/black/labels/T%3A%20design) issue label.
  21
  22 ## Stability Policy
  23
  24 The following policy applies for the _Black_ code style, in non pre-release versions of
  25 _Black_:
  26
  27 - The same code, formatted with the same options, will produce the same output for all
  28   releases in a given calendar year.
  29
  30   This means projects can safely use `black ~= 22.0` without worrying about major
  31   formatting changes disrupting their project in 2022. We may still fix bugs where
  32   _Black_ crashes on some code, and make other improvements that do not affect
  33   formatting.
  34
  35 - The first release in a new calendar year _may_ contain formatting changes, although
  36   these will be minimised as much as possible. This is to allow for improved formatting
  37   enabled by newer Python language syntax as well as due to improvements in the
  38   formatting logic.
  39
  40 - The `--preview` flag is exempt from this policy. There are no guarantees around the
  41   stability of the output with that flag passed into _Black_. This flag is intended for
  42   allowing experimentation with the proposed changes to the _Black_ code style.
  43
  44 Documentation for both the current and future styles can be found:
  45
  46 - {doc}`current_style`
  47 - {doc}`future_style`