[4.0.x] Refs #33476 -- Adjusted docs and config files for Black.

Co-authored-by: Mariusz Felisiak <felisiak.mariusz@gmail.com>

Backport of ba94488196 from main

.editorconfig

@@ -12,7 +12,7 @@ charset = utf-8
 
 # Docstrings and comments use max_line_length = 79
 [*.py]
-max_line_length = 119
+max_line_length = 88
 
 # Use 2 spaces for the HTML files
 [*.html]

.pre-commit-config.yaml

@@ -1,4 +1,8 @@
 repos:
+  - repo: https://github.com/psf/black
+    rev: 22.1.0
+    hooks:
+    - id: black
   - repo: https://github.com/PyCQA/isort
     rev: 5.9.1
     hooks:

docs/internals/contributing/writing-code/coding-style.txt

@@ -35,10 +35,13 @@ them.
 Python style
 ============
 
-* Please conform to the indentation style dictated in the ``.editorconfig``
+* All files should be formatted using the `black`_ auto-formatter. This will be
-  file. We recommend using a text editor with `EditorConfig`_ support to avoid
+  run by ``pre-commit`` if that is configured.
-  indentation and whitespace issues. The Python files use 4 spaces for
+
-  indentation and the HTML files use 2 spaces.
+* The project repository includes an ``.editorconfig`` file. We recommend using
+  a text editor with `EditorConfig`_ support to avoid indentation and
+  whitespace issues. The Python files use 4 spaces for indentation and the HTML
+  files use 2 spaces.
 
 * Unless otherwise specified, follow :pep:`8`.
 
@@ -51,33 +54,11 @@ Python style
 
   An exception to :pep:`8` is our rules on line lengths. Don't limit lines of
   code to 79 characters if it means the code looks significantly uglier or is
-  harder to read. We allow up to 119 characters as this is the width of GitHub
+  harder to read. We allow up to 88 characters as this is the line length used
-  code review; anything longer requires horizontal scrolling which makes review
+  by ``black``. This check is included when you run ``flake8``. Documentation,
-  more difficult. This check is included when you run ``flake8``. Documentation,
   comments, and docstrings should be wrapped at 79 characters, even though
   :pep:`8` suggests 72.
 
-* Use four spaces for indentation.
-
-* Use four space hanging indentation rather than vertical alignment::
-
-    raise AttributeError(
-        'Here is a multiline error message '
-        'shortened for clarity.'
-    )
-
-  Instead of::
-
-      raise AttributeError('Here is a multiline error message '
-                           'shortened for clarity.')
-
-  This makes better use of space and avoids having to realign strings if the
-  length of the first line changes.
-
-* Use single quotes for strings, or a double quote if the string contains a
-  single quote. Don't waste time doing unrelated refactoring of existing code
-  to conform to this style.
-
 * String variable interpolation may use
   :py:ref:`%-formatting <old-string-formatting>`, :py:ref:`f-strings
   <f-strings>`, or :py:meth:`str.format` as appropriate, with the goal of
@@ -146,6 +127,10 @@ Python style
         """
         ...
 
+.. versionchanged:: 4.0.3
+
+    All Python code in Django was reformatted with `black`_.
+
 .. _coding-style-imports:
 
 Imports
@@ -397,5 +382,6 @@ JavaScript style
 For details about the JavaScript code style used by Django, see
 :doc:`javascript`.
 
+.. _black: https://black.readthedocs.io/en/stable/
 .. _editorconfig: https://editorconfig.org/
 .. _flake8: https://pypi.org/project/flake8/

docs/internals/contributing/writing-code/submitting-patches.txt

@@ -290,9 +290,9 @@ All code changes
 
 * Does the :doc:`coding style
   </internals/contributing/writing-code/coding-style>` conform to our
-  guidelines? Are there any ``flake8`` errors? You can install the
+  guidelines? Are there any  ``black``, ``flake8``, or ``isort`` errors? You
-  :ref:`pre-commit <coding-style-pre-commit>` hooks to automatically catch
+  can install the :ref:`pre-commit <coding-style-pre-commit>` hooks to
-  these errors.
+  automatically catch these errors.
 * If the change is backwards incompatible in any way, is there a note
   in the release notes (``docs/releases/A.B.txt``)?
 * Is Django's test suite passing?

docs/internals/contributing/writing-code/unit-tests.txt

@@ -69,16 +69,18 @@ command from any place in the Django source tree:
     $ tox
 
 By default, ``tox`` runs the test suite with the bundled test settings file for
-SQLite, ``flake8``, ``isort``, and the documentation spelling checker. In
+SQLite, ``black``, ``flake8``, ``isort``, and the documentation spelling
-addition to the system dependencies noted elsewhere in this documentation,
+checker. In addition to the system dependencies noted elsewhere in this
-the command ``python3`` must be on your path and linked to the appropriate
+documentation, the command ``python3`` must be on your path and linked to the
-version of Python. A list of default environments can be seen as follows:
+appropriate version of Python. A list of default environments can be seen as
+follows:
 
 .. console::
 
     $ tox -l
     py3
-    flake8
+    black
+    flake8>=3.7.0
     docs
     isort>=5.1.0
 

docs/releases/4.0.3.txt

@@ -4,7 +4,10 @@ Django 4.0.3 release notes
 
 *Expected March 1, 2022*
 
-Django 4.0.3 fixes several bugs in 4.0.2.
+Django 4.0.3 fixes several bugs in 4.0.2. Also, all Python code in Django is
+reformatted with `black`_.
+
+.. _black: https://pypi.org/project/black/
 
 Bugfixes
 ========

pyproject.toml

@@ -1,3 +1,7 @@
 [build-system]
 requires = ['setuptools>=40.8.0', 'wheel']
 build-backend = 'setuptools.build_meta:__legacy__'
+
+[tool.black]
+target-version = ['py38']
+extend-exclude = 'tests/test_runner_apps/tagged/tests_syntax_error.py'

setup.cfg

@@ -57,13 +57,15 @@ install_script = scripts/rpm-install.sh
 
 [flake8]
 exclude = build,.git,.tox,./tests/.env
-ignore = W504,W601
+extend-ignore = E203
-max-line-length = 119
+max-line-length = 88
+per-file-ignores =
+    django/core/cache/backends/filebased.py:W601
+    django/core/cache/backends/base.py:W601
+    django/core/cache/backends/redis.py:W601
+    tests/cache/tests.py:W601
 
 [isort]
-combine_as_imports = true
+profile = black
 default_section = THIRDPARTY
-include_trailing_comma = true
 known_first_party = django
-line_length = 79
-multi_line_output = 5

tox.ini

@@ -8,7 +8,8 @@ minversion = 3.18
 skipsdist = true
 envlist =
     py3
-    flake8
+    black
+    flake8 >= 3.7.0
     docs
     isort >= 5.1.0
 
@@ -31,6 +32,13 @@ changedir = tests
 commands =
     {envpython} runtests.py {posargs}
 
+[testenv:black]
+basepython = python3
+usedevelop = false
+deps = black
+changedir = {toxinidir}
+commands = black --check --diff .
+
 [testenv:flake8]
 basepython = python3
 usedevelop = false