From ee64f3756c0e9c871222b49ac758f174ece21b86 Mon Sep 17 00:00:00 2001 From: cobalt <61329810+RedGuy12@users.noreply.github.com> Date: Mon, 29 Jan 2024 11:57:31 -0600 Subject: [PATCH 01/10] Document E701 in using_black_with_other_tools.md --- docs/guides/using_black_with_other_tools.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md index e642a1aef33..ac78396acb8 100644 --- a/docs/guides/using_black_with_other_tools.md +++ b/docs/guides/using_black_with_other_tools.md @@ -145,7 +145,7 @@ There are a few deviations that cause incompatibilities with _Black_. ``` max-line-length = 88 -extend-ignore = E203, E704 +extend-ignore = E203, E701, E704 ``` #### Why those options above? @@ -173,7 +173,7 @@ limit of `88`, _Black_'s default. This explains `max-line-length = 88`. ```ini [flake8] max-line-length = 88 -extend-ignore = E203, E704 +extend-ignore = E203, E701, E704 ``` @@ -184,7 +184,7 @@ extend-ignore = E203, E704 ```ini [flake8] max-line-length = 88 -extend-ignore = E203, E704 +extend-ignore = E203, E701, E704 ``` @@ -195,7 +195,7 @@ extend-ignore = E203, E704 ```ini [flake8] max-line-length = 88 -extend-ignore = E203, E704 +extend-ignore = E203, E701, E704 ``` From 034029ebfcc510f93ae6c6d04e88f7953d80510d Mon Sep 17 00:00:00 2001 From: cobalt <61329810+RedGuy12@users.noreply.github.com> Date: Mon, 29 Jan 2024 11:58:50 -0600 Subject: [PATCH 02/10] Update current_style.md --- docs/the_black_code_style/current_style.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md index ca5d1d4a701..3a9316316a0 100644 --- a/docs/the_black_code_style/current_style.md +++ b/docs/the_black_code_style/current_style.md @@ -166,7 +166,7 @@ If you use Flake8, you have a few options: max-line-length = 80 ... select = C,E,F,W,B,B950 - extend-ignore = E203, E501, E704 + extend-ignore = E203, E501, E701, E704 ``` The rationale for B950 is explained in @@ -177,7 +177,7 @@ If you use Flake8, you have a few options: ```ini [flake8] max-line-length = 88 - extend-ignore = E203, E704 + extend-ignore = E203, E701, E704 ``` An explanation of why E203 is disabled can be found in the [Slices section](#slices) of From 23367c3fd9974ab8d37def4dc4e972d70a0a5536 Mon Sep 17 00:00:00 2001 From: cobalt <61329810+RedGuy12@users.noreply.github.com> Date: Mon, 29 Jan 2024 11:58:59 -0600 Subject: [PATCH 03/10] Update .flake8 --- .flake8 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.flake8 b/.flake8 index 85f51cf9f05..94d52cbcd5e 100644 --- a/.flake8 +++ b/.flake8 @@ -1,6 +1,6 @@ [flake8] # B905 should be enabled when we drop support for 3.9 -ignore = E203, E266, E501, E704, W503, B905, B907 +ignore = E203, E266, E501, E701, E704, W503, B905, B907 # line length is intentionally set to 80 here because black uses Bugbear # See https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length for more details max-line-length = 80 From 203f7ccafee471c63d29041c4512d6a9a2308465 Mon Sep 17 00:00:00 2001 From: RedGuy12 <61329810+RedGuy12@users.noreply.github.com> Date: Wed, 31 Jan 2024 10:55:41 -0600 Subject: [PATCH 04/10] docs: Refactor pycodestyle/Flake8 compatibility docs Signed-off-by: RedGuy12 <61329810+RedGuy12@users.noreply.github.com> --- .flake8 | 2 +- docs/compatible_configs/flake8/.flake8 | 2 +- docs/compatible_configs/flake8/setup.cfg | 2 +- docs/compatible_configs/flake8/tox.ini | 2 +- docs/compatible_configs/pycodestyle/.flake8 | 3 + docs/compatible_configs/pycodestyle/setup.cfg | 3 + docs/compatible_configs/pycodestyle/tox.ini | 3 + docs/faq.md | 9 +- docs/guides/using_black_with_other_tools.md | 128 ++++++++++-------- docs/the_black_code_style/current_style.md | 39 +----- 10 files changed, 94 insertions(+), 99 deletions(-) create mode 100644 docs/compatible_configs/pycodestyle/.flake8 create mode 100644 docs/compatible_configs/pycodestyle/setup.cfg create mode 100644 docs/compatible_configs/pycodestyle/tox.ini diff --git a/.flake8 b/.flake8 index 94d52cbcd5e..f8dca18e7cf 100644 --- a/.flake8 +++ b/.flake8 @@ -2,7 +2,7 @@ # B905 should be enabled when we drop support for 3.9 ignore = E203, E266, E501, E701, E704, W503, B905, B907 # line length is intentionally set to 80 here because black uses Bugbear -# See https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length for more details +# See https://black.readthedocs.io/en/stable/guides/using_black_with_other_tools.html#bugbear for more details max-line-length = 80 max-complexity = 18 select = B,C,E,F,W,T4,B9 diff --git a/docs/compatible_configs/flake8/.flake8 b/docs/compatible_configs/flake8/.flake8 index 8dd399ab55b..0d4ade348d6 100644 --- a/docs/compatible_configs/flake8/.flake8 +++ b/docs/compatible_configs/flake8/.flake8 @@ -1,3 +1,3 @@ [flake8] max-line-length = 88 -extend-ignore = E203 +extend-ignore = E203,E701 diff --git a/docs/compatible_configs/flake8/setup.cfg b/docs/compatible_configs/flake8/setup.cfg index 8dd399ab55b..0d4ade348d6 100644 --- a/docs/compatible_configs/flake8/setup.cfg +++ b/docs/compatible_configs/flake8/setup.cfg @@ -1,3 +1,3 @@ [flake8] max-line-length = 88 -extend-ignore = E203 +extend-ignore = E203,E701 diff --git a/docs/compatible_configs/flake8/tox.ini b/docs/compatible_configs/flake8/tox.ini index 8dd399ab55b..0d4ade348d6 100644 --- a/docs/compatible_configs/flake8/tox.ini +++ b/docs/compatible_configs/flake8/tox.ini @@ -1,3 +1,3 @@ [flake8] max-line-length = 88 -extend-ignore = E203 +extend-ignore = E203,E701 diff --git a/docs/compatible_configs/pycodestyle/.flake8 b/docs/compatible_configs/pycodestyle/.flake8 new file mode 100644 index 00000000000..34225907524 --- /dev/null +++ b/docs/compatible_configs/pycodestyle/.flake8 @@ -0,0 +1,3 @@ +[pycodestyle] +max-line-length = 88 +ignore = E203,E701 diff --git a/docs/compatible_configs/pycodestyle/setup.cfg b/docs/compatible_configs/pycodestyle/setup.cfg new file mode 100644 index 00000000000..34225907524 --- /dev/null +++ b/docs/compatible_configs/pycodestyle/setup.cfg @@ -0,0 +1,3 @@ +[pycodestyle] +max-line-length = 88 +ignore = E203,E701 diff --git a/docs/compatible_configs/pycodestyle/tox.ini b/docs/compatible_configs/pycodestyle/tox.ini new file mode 100644 index 00000000000..34225907524 --- /dev/null +++ b/docs/compatible_configs/pycodestyle/tox.ini @@ -0,0 +1,3 @@ +[pycodestyle] +max-line-length = 88 +ignore = E203,E701 diff --git a/docs/faq.md b/docs/faq.md index 124a096efac..fc85866d24e 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -77,13 +77,10 @@ following will not be formatted: - invalid syntax, as it can't be safely distinguished from automagics in the absence of a running `IPython` kernel. -## Why are Flake8's E203 and W503 violated? +## Why does Flake8 report warnings? -Because they go against PEP 8. E203 falsely triggers on list -[slices](the_black_code_style/current_style.md#slices), and adhering to W503 hinders -readability because operators are misaligned. Disable W503 and enable the -disabled-by-default counterpart W504. E203 should be disabled while changes are still -[discussed](https://github.com/PyCQA/pycodestyle/issues/373). +See +[Using _Black_ with other tools](guides/using_black_with_other_tools.md#why-pycodestyle-warnings). ## Which Python versions does Black support? diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md index ac78396acb8..7ef63d52f6a 100644 --- a/docs/guides/using_black_with_other_tools.md +++ b/docs/guides/using_black_with_other_tools.md @@ -134,10 +134,10 @@ profile = black -### Flake8 +### pycodestyle -[Flake8](https://pypi.org/p/flake8/) is a code linter. It warns you of syntax errors, -possible bugs, stylistic errors, etc. For the most part, Flake8 follows +[pycodestyle](https://pycodestyle.pycqa.org/) is a code linter. It warns you of syntax +errors, possible bugs, stylistic errors, etc. For the most part, pycodestyle follows [PEP 8](https://www.python.org/dev/peps/pep-0008/) when warning about stylistic errors. There are a few deviations that cause incompatibilities with _Black_. @@ -145,67 +145,113 @@ There are a few deviations that cause incompatibilities with _Black_. ``` max-line-length = 88 -extend-ignore = E203, E701, E704 +ignore = E203,E701 ``` +(labels/why-pycodestyle-warnings)= + #### Why those options above? +##### `max-line-length` + +As with isort, pycodestyle should be configured to allow lines up to the length limit of +`88`, _Black_'s default. + +##### `E203` + In some cases, as determined by PEP 8, _Black_ will enforce an equal amount of -whitespace around slice operators. Due to this, Flake8 will raise -`E203 whitespace before ':'` warnings. Since this warning is not PEP 8 compliant, Flake8 -should be configured to ignore it via `extend-ignore = E203`. +whitespace around slice operators. Due to this, pycodestyle will raise +`E203 whitespace before ':'` warnings. Since this warning is not PEP 8 compliant, it +should be disabled. + +##### `E701` / `E704` + +PEP 8 states (and has always stated), "Blank lines may be omitted between a bunch of +related one-liners." _Black_ takes advantage of this by putting the pass statement of +dummy implementations on the same line as the colon, reducing the number of lines while +improving readability. This does go against pycodestyle's +`E701 multiple statements on one line (colon)`. Its disabled-by-default +`E704 multiple statements on one line (def)` rule may also raise warnings in this +situation and should not be enabled. + +##### `W503` When breaking a line, _Black_ will break it before a binary operator. This is compliant with PEP 8 as of [April 2016](https://github.com/python/peps/commit/c59c4376ad233a62ca4b3a6060c81368bd21e85b#diff-64ec08cc46db7540f18f2af46037f599). There's a disabled-by-default warning in Flake8 which goes against this PEP 8 recommendation called `W503 line break before binary operator`. It should not be enabled -in your configuration. - -Also, as like with isort, flake8 should be configured to allow lines up to the length -limit of `88`, _Black_'s default. This explains `max-line-length = 88`. +in your configuration. You should use its counterpart +`W504 line break after binary operator` instead. #### Formats
-.flake8 +setup.cfg, .pycodestyle, tox.ini ```ini -[flake8] +[pycodestyle] max-line-length = 88 -extend-ignore = E203, E701, E704 +ignore = E203,E701 ```
-
-setup.cfg +### Flake8 -```ini +[Flake8](https://pypi.org/p/flake8/) is a wrapper around multiple linters, including +pycodestyle. As such, it has many of the same issues + +#### Bugbear + +It's recommended to use [the Bugbear plugin](https://github.com/PyCQA/flake8-bugbear) +and enabling +[its B950 check](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings#:~:text=you%20expect%20it.-,B950,-%3A%20Line%20too%20long) +instead of using Flake8's E501, because it aligns with +[Black's 10% rule](the_black_code_style/current_style.md#line-length). + +Install Bugbear and use the following config: + +``` +[flake8] +max-line-length = 80 +extend-select = B950 +extend-ignore = E203,E501,E701 +``` + +#### Minimal Configuration + +In cases where you can't or don't want to install Bugbear, you can use this minimally +compatible config: + +``` [flake8] max-line-length = 88 -extend-ignore = E203, E701, E704 +extend-ignore = E203,E701 ``` -
+#### Why those options above? + +See [the pycodestyle section](#why-pycodestyle-warnings) above. + +#### Formats
-tox.ini +.flake8, setup.cfg, tox.ini ```ini [flake8] max-line-length = 88 -extend-ignore = E203, E701, E704 +extend-ignore = E203,E701 ```
### Pylint -[Pylint](https://pypi.org/p/pylint/) is also a code linter like Flake8. It has the same -checks as flake8 and more. In particular, it has more formatting checks regarding style -conventions like variable naming. With so many checks, Pylint is bound to have some -mixed feelings about _Black_'s formatting style. +[Pylint](https://pypi.org/p/pylint/) is also a code linter like Flake8. It has many of +the same checks as Flake8 and more. It particularly has more formatting checks regarding +style conventions like variable naming. #### Configuration @@ -252,35 +298,3 @@ max-line-length = "88" ``` - -### pycodestyle - -[pycodestyle](https://pycodestyle.pycqa.org/) is also a code linter like Flake8. - -#### Configuration - -``` -max-line-length = 88 -ignore = E203 -``` - -#### Why those options above? - -pycodestyle should be configured to only complain about lines that surpass `88` -characters via `max_line_length = 88`. - -See -[Why are Flake8’s E203 and W503 violated?](https://black.readthedocs.io/en/stable/faq.html#why-are-flake8-s-e203-and-w503-violated) - -#### Formats - -
-setup.cfg - -```cfg -[pycodestyle] -ignore = E203 -max_line_length = 88 -``` - -
diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md index 3a9316316a0..719b259244d 100644 --- a/docs/the_black_code_style/current_style.md +++ b/docs/the_black_code_style/current_style.md @@ -143,45 +143,20 @@ significantly shorter files than sticking with 80 (the most popular), or even 79 by the standard library). In general, [90-ish seems like the wise choice](https://youtu.be/wf-BqAjZb8M?t=260). -If you're paid by the line of code you write, you can pass `--line-length` with a lower -number. _Black_ will try to respect that. However, sometimes it won't be able to without -breaking other rules. In those rare cases, auto-formatted code will exceed your allotted -limit. +If you're paid by the number of lines of code you write, you can pass `--line-length` +with a lower number. _Black_ will try to respect that. However, sometimes it won't be +able to without breaking other rules. In those rare cases, auto-formatted code will +exceed your allotted limit. You can also increase it, but remember that people with sight disabilities find it harder to work with line lengths exceeding 100 characters. It also adversely affects side-by-side diff review on typical screen resolutions. Long lines also make it harder to present code neatly in documentation or talk slides. -#### Flake8 +#### Flake8 / pycodestyle -If you use Flake8, you have a few options: - -1. Recommended is using [Bugbear](https://github.com/PyCQA/flake8-bugbear) and enabling - its B950 check instead of using Flake8's E501, because it aligns with Black's 10% - rule. Install Bugbear and use the following config: - - ```ini - [flake8] - max-line-length = 80 - ... - select = C,E,F,W,B,B950 - extend-ignore = E203, E501, E701, E704 - ``` - - The rationale for B950 is explained in - [Bugbear's documentation](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings). - -2. For a minimally compatible config: - - ```ini - [flake8] - max-line-length = 88 - extend-ignore = E203, E701, E704 - ``` - -An explanation of why E203 is disabled can be found in the [Slices section](#slices) of -this page. +See [Using _Black_ with other tools](guides/using_black_with_other_tools.md) about +linter compatibility. ### Empty lines From 6281f48d8a61bceb18c6c2ebd5e3c016956100cb Mon Sep 17 00:00:00 2001 From: RedGuy12 <61329810+RedGuy12@users.noreply.github.com> Date: Wed, 31 Jan 2024 11:15:09 -0600 Subject: [PATCH 05/10] docs: Fix links Signed-off-by: RedGuy12 <61329810+RedGuy12@users.noreply.github.com> --- docs/faq.md | 3 +-- docs/guides/using_black_with_other_tools.md | 6 +++--- docs/the_black_code_style/current_style.md | 5 +++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index fc85866d24e..6d553f39fd5 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -79,8 +79,7 @@ following will not be formatted: ## Why does Flake8 report warnings? -See -[Using _Black_ with other tools](guides/using_black_with_other_tools.md#why-pycodestyle-warnings). +See [Using _Black_ with other tools](labels/why-pycodestyle-warnings). ## Which Python versions does Black support? diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md index 7ef63d52f6a..606f961a87a 100644 --- a/docs/guides/using_black_with_other_tools.md +++ b/docs/guides/using_black_with_other_tools.md @@ -200,7 +200,7 @@ ignore = E203,E701 ### Flake8 [Flake8](https://pypi.org/p/flake8/) is a wrapper around multiple linters, including -pycodestyle. As such, it has many of the same issues +pycodestyle. As such, it has many of the same issues. #### Bugbear @@ -208,7 +208,7 @@ It's recommended to use [the Bugbear plugin](https://github.com/PyCQA/flake8-bug and enabling [its B950 check](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings#:~:text=you%20expect%20it.-,B950,-%3A%20Line%20too%20long) instead of using Flake8's E501, because it aligns with -[Black's 10% rule](the_black_code_style/current_style.md#line-length). +[Black's 10% rule](labels/line-length). Install Bugbear and use the following config: @@ -232,7 +232,7 @@ extend-ignore = E203,E701 #### Why those options above? -See [the pycodestyle section](#why-pycodestyle-warnings) above. +See [the pycodestyle section](labels/why-pycodestyle-warnings) above. #### Formats diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md index 719b259244d..9c6058f71a2 100644 --- a/docs/the_black_code_style/current_style.md +++ b/docs/the_black_code_style/current_style.md @@ -155,8 +155,9 @@ to present code neatly in documentation or talk slides. #### Flake8 / pycodestyle -See [Using _Black_ with other tools](guides/using_black_with_other_tools.md) about -linter compatibility. +See +[Using _Black_ with other tools](../guides/using_black_with_other_tools.md#pycodestyle) +about linter compatibility. ### Empty lines From abe43cf05cd7dd0aa37c7a9dfb154124e3f22c78 Mon Sep 17 00:00:00 2001 From: cobalt <61329810+RedGuy12@users.noreply.github.com> Date: Thu, 1 Feb 2024 09:45:28 -0600 Subject: [PATCH 06/10] Update docs/guides/using_black_with_other_tools.md Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com> --- docs/guides/using_black_with_other_tools.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md index 606f961a87a..bcb41e16fc4 100644 --- a/docs/guides/using_black_with_other_tools.md +++ b/docs/guides/using_black_with_other_tools.md @@ -166,13 +166,16 @@ should be disabled. ##### `E701` / `E704` -PEP 8 states (and has always stated), "Blank lines may be omitted between a bunch of -related one-liners." _Black_ takes advantage of this by putting the pass statement of -dummy implementations on the same line as the colon, reducing the number of lines while -improving readability. This does go against pycodestyle's -`E701 multiple statements on one line (colon)`. Its disabled-by-default -`E704 multiple statements on one line (def)` rule may also raise warnings in this -situation and should not be enabled. +_Black_ will collapse implementations of classes and functions consisting solely +of "..." on to a single line. This matches how such examples are formatted in +PEP 8. It remains true that in all other cases Black will prevent multiple +statements on the same line, in accordance with PEP 8 generally +discouraging this. + +However, `pycodestyle` does not mirror this logic and may raise +`E701 multiple statements on one line (colon)` in this situation. +Its disabled-by-default `E704 multiple statements on one line (def)` rule may +also raise warnings and should not be enabled. ##### `W503` From 330f550dd7aa668901406585715b8d15da4999f3 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 1 Feb 2024 15:46:02 +0000 Subject: [PATCH 07/10] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/guides/using_black_with_other_tools.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md index bcb41e16fc4..f40bdde88cb 100644 --- a/docs/guides/using_black_with_other_tools.md +++ b/docs/guides/using_black_with_other_tools.md @@ -166,16 +166,15 @@ should be disabled. ##### `E701` / `E704` -_Black_ will collapse implementations of classes and functions consisting solely -of "..." on to a single line. This matches how such examples are formatted in -PEP 8. It remains true that in all other cases Black will prevent multiple -statements on the same line, in accordance with PEP 8 generally -discouraging this. +_Black_ will collapse implementations of classes and functions consisting solely of +"..." on to a single line. This matches how such examples are formatted in PEP 8. It +remains true that in all other cases Black will prevent multiple statements on the same +line, in accordance with PEP 8 generally discouraging this. However, `pycodestyle` does not mirror this logic and may raise -`E701 multiple statements on one line (colon)` in this situation. -Its disabled-by-default `E704 multiple statements on one line (def)` rule may -also raise warnings and should not be enabled. +`E701 multiple statements on one line (colon)` in this situation. Its +disabled-by-default `E704 multiple statements on one line (def)` rule may also raise +warnings and should not be enabled. ##### `W503` From 2c1a0c36907922c6e371be9c3e4f6c5db9bd141d Mon Sep 17 00:00:00 2001 From: RedGuy12 <61329810+RedGuy12@users.noreply.github.com> Date: Thu, 1 Feb 2024 10:00:32 -0600 Subject: [PATCH 08/10] or pass Signed-off-by: RedGuy12 <61329810+RedGuy12@users.noreply.github.com> --- docs/guides/using_black_with_other_tools.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md index f40bdde88cb..d6b641c416b 100644 --- a/docs/guides/using_black_with_other_tools.md +++ b/docs/guides/using_black_with_other_tools.md @@ -167,9 +167,9 @@ should be disabled. ##### `E701` / `E704` _Black_ will collapse implementations of classes and functions consisting solely of -"..." on to a single line. This matches how such examples are formatted in PEP 8. It -remains true that in all other cases Black will prevent multiple statements on the same -line, in accordance with PEP 8 generally discouraging this. +"..." or "pass" on to a single line. This matches how such examples are formatted in +PEP 8. It remains true that in all other cases Black will prevent multiple statements on +the same line, in accordance with PEP 8 generally discouraging this. However, `pycodestyle` does not mirror this logic and may raise `E701 multiple statements on one line (colon)` in this situation. Its From 6c6ce487007e0ebc1ffbfefa8497f1bfa4ea0203 Mon Sep 17 00:00:00 2001 From: RedGuy12 <61329810+RedGuy12@users.noreply.github.com> Date: Thu, 1 Feb 2024 10:48:08 -0600 Subject: [PATCH 09/10] Apply suggestions from code review Co-authored-by: Jelle Zijlstra Signed-off-by: RedGuy12 <61329810+RedGuy12@users.noreply.github.com> --- docs/faq.md | 1 + docs/guides/using_black_with_other_tools.md | 10 +++++----- docs/the_black_code_style/current_style.md | 15 +++++++-------- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 6d553f39fd5..d19ff8e7ace 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -79,6 +79,7 @@ following will not be formatted: ## Why does Flake8 report warnings? +Some of Flake8's rules conflict with Black's style. We recommend disabling these rules. See [Using _Black_ with other tools](labels/why-pycodestyle-warnings). ## Which Python versions does Black support? diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md index d6b641c416b..5c964c1600c 100644 --- a/docs/guides/using_black_with_other_tools.md +++ b/docs/guides/using_black_with_other_tools.md @@ -167,9 +167,9 @@ should be disabled. ##### `E701` / `E704` _Black_ will collapse implementations of classes and functions consisting solely of -"..." or "pass" on to a single line. This matches how such examples are formatted in -PEP 8. It remains true that in all other cases Black will prevent multiple statements on -the same line, in accordance with PEP 8 generally discouraging this. +"..." or "pass" to a single line. This matches how such examples are formatted in PEP 8. +It remains true that in all other cases Black will prevent multiple statements on the +same line, in accordance with PEP 8 generally discouraging this. However, `pycodestyle` does not mirror this logic and may raise `E701 multiple statements on one line (colon)` in this situation. Its @@ -183,7 +183,7 @@ with PEP 8 as of [April 2016](https://github.com/python/peps/commit/c59c4376ad233a62ca4b3a6060c81368bd21e85b#diff-64ec08cc46db7540f18f2af46037f599). There's a disabled-by-default warning in Flake8 which goes against this PEP 8 recommendation called `W503 line break before binary operator`. It should not be enabled -in your configuration. You should use its counterpart +in your configuration. You can use its counterpart `W504 line break after binary operator` instead. #### Formats @@ -207,7 +207,7 @@ pycodestyle. As such, it has many of the same issues. #### Bugbear It's recommended to use [the Bugbear plugin](https://github.com/PyCQA/flake8-bugbear) -and enabling +and enable [its B950 check](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings#:~:text=you%20expect%20it.-,B950,-%3A%20Line%20too%20long) instead of using Flake8's E501, because it aligns with [Black's 10% rule](labels/line-length). diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md index 9c6058f71a2..586c79074af 100644 --- a/docs/the_black_code_style/current_style.md +++ b/docs/the_black_code_style/current_style.md @@ -143,21 +143,20 @@ significantly shorter files than sticking with 80 (the most popular), or even 79 by the standard library). In general, [90-ish seems like the wise choice](https://youtu.be/wf-BqAjZb8M?t=260). -If you're paid by the number of lines of code you write, you can pass `--line-length` -with a lower number. _Black_ will try to respect that. However, sometimes it won't be -able to without breaking other rules. In those rare cases, auto-formatted code will -exceed your allotted limit. +If you're paid by the lines of code you write, you can pass `--line-length` with a lower +number. _Black_ will try to respect that. However, sometimes it won't be able to without +breaking other rules. In those rare cases, auto-formatted code will exceed your allotted +limit. You can also increase it, but remember that people with sight disabilities find it harder to work with line lengths exceeding 100 characters. It also adversely affects side-by-side diff review on typical screen resolutions. Long lines also make it harder to present code neatly in documentation or talk slides. -#### Flake8 / pycodestyle +#### Flake8 and other linters -See -[Using _Black_ with other tools](../guides/using_black_with_other_tools.md#pycodestyle) -about linter compatibility. +See [Using _Black_ with other tools](../guides/using_black_with_other_tools.md) about +linter compatibility. ### Empty lines From a9d28ae098065b251e8405af963bb1255a935e16 Mon Sep 17 00:00:00 2001 From: RedGuy12 <61329810+RedGuy12@users.noreply.github.com> Date: Thu, 1 Feb 2024 10:53:29 -0600 Subject: [PATCH 10/10] actually, black does not condense `pass` Signed-off-by: RedGuy12 <61329810+RedGuy12@users.noreply.github.com> --- docs/guides/using_black_with_other_tools.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/using_black_with_other_tools.md b/docs/guides/using_black_with_other_tools.md index 5c964c1600c..187e3a3e6f5 100644 --- a/docs/guides/using_black_with_other_tools.md +++ b/docs/guides/using_black_with_other_tools.md @@ -166,10 +166,10 @@ should be disabled. ##### `E701` / `E704` -_Black_ will collapse implementations of classes and functions consisting solely of -"..." or "pass" to a single line. This matches how such examples are formatted in PEP 8. -It remains true that in all other cases Black will prevent multiple statements on the -same line, in accordance with PEP 8 generally discouraging this. +_Black_ will collapse implementations of classes and functions consisting solely of `..` +to a single line. This matches how such examples are formatted in PEP 8. It remains true +that in all other cases Black will prevent multiple statements on the same line, in +accordance with PEP 8 generally discouraging this. However, `pycodestyle` does not mirror this logic and may raise `E701 multiple statements on one line (colon)` in this situation. Its