Formatting Code with Black

[Mariusz Felisiak]

Based on ​DEP-8 accepted by the Technical Board.

The first stable version of Black has been released, see ​22.1.0.

I assigned it to myself, but we will be working on this with Carlton and the Ops Team.

See ​implementation.

[Carlton Gibson <carlton@…>]

In ca88caa1:

Refs #33476 -- Used vertical hanging indentation for format lists with inline comments.

Lists with multiple values and comments per-line are reformatted
by Black to multiple lines with a single comment. For example:

DATE_INPUT_FORMATS =

"%Y-%m-%d", "%m/%d/%Y", "%m/%d/%y", # '2006-10-25', '10/25/2006', '10/25/06'

]

is reformatted to the:

DATE_INPUT_FORMATS =

"%Y-%m-%d",
"%m/%d/%Y",
"%m/%d/%y", # '2006-10-25', '10/25/2006', '10/25/06'

]

This reformats affected entries to multiple lines with corresponding
comments.

[Carlton Gibson <carlton.gibson@…>]

In 0c06819c:

[4.0.x] Refs #33476 -- Used vertical hanging indentation for format lists with inline comments.

Lists with multiple values and comments per-line are reformatted
by Black to multiple lines with a single comment. For example:

DATE_INPUT_FORMATS =

"%Y-%m-%d", "%m/%d/%Y", "%m/%d/%y", # '2006-10-25', '10/25/2006', '10/25/06'

]

is reformatted to the:

DATE_INPUT_FORMATS =

"%Y-%m-%d",
"%m/%d/%Y",
"%m/%d/%y", # '2006-10-25', '10/25/2006', '10/25/06'

]

This reformats affected entries to multiple lines with corresponding
comments.

Backport of ca88caa1031c0de545d82de8d90dcae0e03651fb from main

[Nikita Marchant]

The DEP also ​mentions that "All code Django generates will also be Black-formatted (startproject, migrations, inspectdb, etc.)" but there is nothing in the "Reference Implementation" part that specifies how to do this.

There is a ​mention on the mailing-list of maybe using django-migrations-formatter. Would upstreaming the feature be a welcome contribution (the license - BSD - matches) for this ticket ?

Also, would reformatting files in django/conf/project_template/ and django/conf/app_template/ (by hand, they are not all valid python) to follow Black style be a welcome contribution ? (Note that this can not guarantee that the generated files will be Black formatted, especially when templates variables are very long and Black would want to wrap lines)

[Mariusz Felisiak]

Replying to Nikita Marchant:

The DEP also ​mentions that "All code Django generates will also be Black-formatted (startproject, migrations, inspectdb, etc.)" but there is nothing in the "Reference Implementation" part that specifies how to do this.

There is a ​mention on the mailing-list of maybe using django-migrations-formatter. Would upstreaming the feature be a welcome contribution (the license - BSD - matches) for this ticket ?

Also, would reformatting files in django/conf/project_template/ and django/conf/app_template/ (by hand, they are not all valid python) to follow Black style be a welcome contribution ? (Note that this can not guarantee that the generated files will be Black formatted, especially when templates variables are very long and Black would want to wrap lines)

As far as I'm aware, we'd like to use a different approach, i.e. run black on generated files but only when it's installed.

[GitHub <noreply@…>]

In c5cd8783:

Refs #33476 -- Refactored problematic code before reformatting by Black.

In these cases Black produces unexpected results, e.g.

def make_random_password(

self,
length=10,
allowed_chars='abcdefghjkmnpqrstuvwxyz' 'ABCDEFGHJKLMNPQRSTUVWXYZ' '23456789',

):

or

cursor.execute("""
SELECT ...
""",

[table name],

)

[Mariusz Felisiak <felisiak.mariusz@…>]

In d55a1e5:

[4.0.x] Refs #33476 -- Refactored problematic code before reformatting by Black.

In these cases Black produces unexpected results, e.g.

def make_random_password(

self,
length=10,
allowed_chars='abcdefghjkmnpqrstuvwxyz' 'ABCDEFGHJKLMNPQRSTUVWXYZ' '23456789',

):

or

cursor.execute("""
SELECT ...
""",

[table name],

)

Backport of c5cd8783825b5f6384417dac5f3889b4210b7d08 from main.

[Mariusz Felisiak <felisiak.mariusz@…>]

In ba94488:

Refs #33476 -- Adjusted docs and config files for Black.

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

[Mariusz Felisiak <felisiak.mariusz@…>]

In cf5e61cf:

Refs #33476 -- Added GitHub action to run black linter.

[Mariusz Felisiak <felisiak.mariusz@…>]

In f68fa8b:

Refs #33476 -- Changed quotation marks in DebugViewTests.test_template_exceptions().

This prevents a failure after reformatting the code with Black.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 9c19aff7:

Refs #33476 -- Reformatted code with Black.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 7119f40c:

Refs #33476 -- Refactored code to strictly match 88 characters line length.

[Mariusz Felisiak <felisiak.mariusz@…>]

In b9fee0f8:

Refs #33476 -- Ignored formatting changes in git blame.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 9a7755f:

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

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

Backport of ba94488196a74e312177ef2621fbd427956836ef from main

[Mariusz Felisiak <felisiak.mariusz@…>]

In 224c64a:

[4.0.x] Refs #33476 -- Added GitHub action to run black linter.

Backport of cf5e61cf6c721121abf7347baff3d41a0ad3c23e from main

[Mariusz Felisiak <felisiak.mariusz@…>]

In e73ce088:

[4.0.x] Refs #33476 -- Changed quotation marks in DebugViewTests.test_template_exceptions().

This prevents a failure after reformatting the code with Black.

Backport of f68fa8b45dfac545cfc4111d4e52804c86db68d3 from main

[Mariusz Felisiak <felisiak.mariusz@…>]

In 6a682b3:

[4.0.x] Refs #33476 -- Reformatted code with Black.

Backport of 9c19aff7c7561e3a82978a272ecdaad40dda5c00 from main.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 3278c31f:

[4.0.x] Refs #33476 -- Refactored code to strictly match 88 characters line length.

Backport of 7119f40c9881666b6f9b5cf7df09ee1d21cc8344 from main.

[Mariusz Felisiak <felisiak.mariusz@…>]

In f2d3e1fc:

[4.0.x] Refs #33476 -- Ignored formatting changes in git blame.

[Mariusz Felisiak <felisiak.mariusz@…>]

In d113b5a:

Refs #33476 -- Made management commands use black.

Run black on generated files, if it is available on PATH.

[Mariusz Felisiak <felisiak.mariusz@…>]

In fe3518d2:

Refs #33476 -- Mentioned black in docs about pre-commit checks.

[Mariusz Felisiak <felisiak.mariusz@…>]

In be4a1069:

[4.0.x] Refs #33476 -- Mentioned black in docs about pre-commit checks.

Backport of fe3518d25edd69b782339729080b0295a8a33952 from main

[GitHub <noreply@…>]

In d11944be:

Refs #33476 -- Added warning to optimizemigration/squashmigrations commands when black cannot be applied.

[Carlton Gibson <carlton@…>]

In fa948980:

Refs #33476 -- Used black's force-exclude instead of extend-exclude.

When using pre-commit run --all-files, because the filename is passed
explicitly, the file referred to in extend-exclude is not properly
excluded. Use force-exclude instead to say we really mean it.

See ​https://github.com/psf/black/issues/438.

[Carlton Gibson <carlton@…>]

In b1005c0:

Refs #33476 -- Prevented formatting of .py-tpl files with black by pre-commit.

When using pre-commit run --all-files, files explicitly passed to
black are processed even if they don't match the include configuration
option. For some reason, (only) one of the *.py-tpl files is picked up
by pre-commit. We can avoid this by explicitly excluding certain
patterns of files for the black hook in the pre-commit configuration.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 097e3a7:

Refs #33476 -- Applied Black's 2023 stable style.

Black 23.1.0 is released which, as the first release of the year,
introduces the 2023 stable style. This incorporates most of last year's
preview style.

​https://github.com/psf/black/releases/tag/23.1.0

[Mariusz Felisiak <felisiak.mariusz@…>]

In 80aae834:

[4.2.x] Refs #33476 -- Applied Black's 2023 stable style.

Black 23.1.0 is released which, as the first release of the year,
introduces the 2023 stable style. This incorporates most of last year's
preview style.

​https://github.com/psf/black/releases/tag/23.1.0

Backport of 097e3a70c1481ee7b042b2edd91b2be86fb7b5b6 from main

[Mariusz Felisiak <felisiak.mariusz@…>]

In a637d0bd:

[4.1.x] Refs #33476 -- Applied Black's 2023 stable style.

Black 23.1.0 is released which, as the first release of the year,
introduces the 2023 stable style. This incorporates most of last year's
preview style.

​https://github.com/psf/black/releases/tag/23.1.0

Backport of 097e3a70c1481ee7b042b2edd91b2be86fb7b5b6 from main.

[Mariusz Felisiak <felisiak.mariusz@…>]

In e565a5cd:

[4.0.x] Refs #33476 -- Applied Black's 2023 stable style.

Black 23.1.0 is released which, as the first release of the year,
introduces the 2023 stable style. This incorporates most of last year's
preview style.

​https://github.com/psf/black/releases/tag/23.1.0

Backport of 097e3a70c1481ee7b042b2edd91b2be86fb7b5b6 from main.