docs/the_black_code_style/index.rst

   1 The Black Code Style
   2 ====================
   3
   4 .. toctree::
   5     :hidden:
   6
   7     Current style <current_style>
   8     Future style <future_style>
   9
  10 *Black* is a PEP 8 compliant opinionated formatter with its own style.
  11
  12 While keeping the style unchanged throughout releases has always been a goal,
  13 the *Black* code style isn't set in stone. It evolves to accomodate for new features
  14 in the Python language and, ocassionally, in response to user feedback.
  15
  16 Stability Policy
  17 ----------------
  18
  19 The following policy applies for the *Black* code style, in non pre-release
  20 versions of *Black*:
  21
  22 - The same code, formatted with the same options, will produce the same
  23   output for all releases in a given calendar year.
  24
  25   This means projects can safely use `black ~= 22.0` without worrying about
  26   major formatting changes disrupting their project in 2022. We may still
  27   fix bugs where *Black* crashes on some code, and make other improvements
  28   that do not affect formatting.
  29
  30 - The first release in a new calendar year *may* contain formatting changes,
  31   although these will be minimised as much as possible. This is to allow for
  32   improved formatting enabled by newer Python language syntax as well as due
  33   to improvements in the formatting logic.
  34
  35 - The ``--future`` flag is exempt from this policy. There are no guarentees
  36   around the stability of the output with that flag passed into *Black*. This
  37   flag is intended for allowing experimentation with the proposed changes to
  38   the *Black* code style.
  39
  40 Documentation for both the current and future styles can be found:
  41
  42 - :doc:`current_style`
  43 - :doc:`future_style`