From e75b9eb34eee18355d9c3089fbdbc626d4c58609 Mon Sep 17 00:00:00 2001 From: Antti Kaihola <13725+akaihola@users.noreply.github.com> Date: Sat, 30 Mar 2024 22:13:34 +0200 Subject: [PATCH 1/6] Deprecate 2 Black config options in [tool.darker] --- constraints-oldest.txt | 1 + setup.cfg | 2 +- src/darker/command_line.py | 20 ++++++++++++++++++-- src/darker/config.py | 3 +++ 4 files changed, 23 insertions(+), 3 deletions(-) diff --git a/constraints-oldest.txt b/constraints-oldest.txt index 051607bfb..89ce1fe8e 100644 --- a/constraints-oldest.txt +++ b/constraints-oldest.txt @@ -5,6 +5,7 @@ # versions in `setup.cfg`. airium==0.2.3 black==22.3.0 +darkgraylib==1.2.0 defusedxml==0.7.1 flake8-2020==1.6.1 flake8-bugbear==22.1.11 diff --git a/setup.cfg b/setup.cfg index 1713055cb..8ba5b2a9b 100644 --- a/setup.cfg +++ b/setup.cfg @@ -29,7 +29,7 @@ packages = find: install_requires = # NOTE: remember to keep `constraints-oldest.txt` in sync with these black>=22.3.0 - darkgraylib~=1.1.1 + darkgraylib~=1.2.0 graylint~=1.0.1 toml>=0.10.0 # NOTE: remember to keep `.github/workflows/python-package.yml` in sync diff --git a/src/darker/command_line.py b/src/darker/command_line.py index 04dd17078..8cd63f036 100644 --- a/src/darker/command_line.py +++ b/src/darker/command_line.py @@ -1,5 +1,6 @@ """Command line parsing for the ``darker`` binary""" +import warnings from argparse import ArgumentParser, Namespace from functools import partial from typing import List, Optional, Tuple @@ -8,7 +9,7 @@ import darkgraylib.command_line from darker import help as hlp -from darker.config import DarkerConfig, OutputMode +from darker.config import DEPRECATED_CONFIG_OPTIONS, DarkerConfig, OutputMode from darkgraylib.command_line import add_parser_argument from graylint.command_line import add_lint_arg @@ -78,6 +79,17 @@ def make_argument_parser(require_src: bool) -> ArgumentParser: return parser +def show_config_deprecations(config: DarkerConfig) -> None: + """Show deprecation warnings for configuration keys from the config file.""" + for option in DEPRECATED_CONFIG_OPTIONS & set(config): + warnings.warn( + f"The configuration option `{option}` in [tool.darker] is deprecated" + " and will be removed in Darker 3.0.", + DeprecationWarning, + stacklevel=2, + ) + + def parse_command_line( argv: Optional[List[str]], ) -> Tuple[Namespace, DarkerConfig, DarkerConfig]: @@ -96,7 +108,11 @@ def parse_command_line( """ args, effective_cfg, modified_cfg = darkgraylib.command_line.parse_command_line( - make_argument_parser, argv, "darker", DarkerConfig + make_argument_parser, + argv, + "darker", + DarkerConfig, + show_config_deprecations, ) OutputMode.validate_diff_stdout(args.diff, args.stdout) OutputMode.validate_stdout_src(args.stdout, args.src, args.stdin_filename) diff --git a/src/darker/config.py b/src/darker/config.py index 6db29da8c..1324901b0 100644 --- a/src/darker/config.py +++ b/src/darker/config.py @@ -10,6 +10,9 @@ UnvalidatedConfig = Dict[str, Union[List[str], str, bool, int]] +DEPRECATED_CONFIG_OPTIONS = {"skip_string_normalization", "skip_magic_trailing_comma"} + + class DarkerConfig(BaseConfig, total=False): """Dictionary representing ``[tool.darker]`` from ``pyproject.toml``""" From 9e05855fd892be8f74fb08fb237acb8c78c10abf Mon Sep 17 00:00:00 2001 From: Antti Kaihola <13725+akaihola@users.noreply.github.com> Date: Sat, 30 Mar 2024 22:58:17 +0200 Subject: [PATCH 2/6] Add unit test for Black config option deprecations --- src/darker/tests/test_command_line.py | 57 +++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/src/darker/tests/test_command_line.py b/src/darker/tests/test_command_line.py index 719e5a9fe..2ce04c9e4 100644 --- a/src/darker/tests/test_command_line.py +++ b/src/darker/tests/test_command_line.py @@ -11,6 +11,7 @@ from unittest.mock import DEFAULT, Mock, call, patch import pytest +import toml from black import TargetVersion import darker.help @@ -243,6 +244,62 @@ def test_parse_command_line( ) +@pytest.mark.kwparametrize( + dict(config={}, expect_warn=set()), + dict(config={"diff": True}, expect_warn=set()), + dict(config={"stdout": True}, expect_warn=set()), + dict(config={"check": True}, expect_warn=set()), + dict(config={"isort": True}, expect_warn=set()), + dict(config={"lint": ["pylint"]}, expect_warn=set()), + dict( + config={"skip_string_normalization": True}, + expect_warn={ + "The configuration option `skip_string_normalization` in [tool.darker] is" + " deprecated and will be removed in Darker 3.0." + }, + ), + dict( + config={"skip_magic_trailing_comma": True}, + expect_warn={ + "The configuration option `skip_magic_trailing_comma` in [tool.darker] is" + " deprecated and will be removed in Darker 3.0." + }, + ), + dict(config={"line_length": 88}, expect_warn=set()), + dict(config={"target_version": "py37"}, expect_warn=set()), + dict( + config={ + "diff": True, + "stdout": False, + "check": True, + "isort": True, + "lint": ["pylint"], + "skip_string_normalization": True, + "skip_magic_trailing_comma": True, + "line_length": 88, + "target_version": "py37", + }, + expect_warn={ + "The configuration option `skip_magic_trailing_comma` in [tool.darker] is" + " deprecated and will be removed in Darker 3.0.", + "The configuration option `skip_string_normalization` in [tool.darker] is" + " deprecated and will be removed in Darker 3.0.", + }, + ), +) +def test_parse_command_line_deprecated_option( + tmp_path, monkeypatch, config, expect_warn +): + """`parse_command_line` warns about deprecated configuration options.""" + monkeypatch.chdir(tmp_path) + (tmp_path / "pyproject.toml").write_text(toml.dumps({"tool": {"darker": config}})) + with patch("darker.command_line.warnings.warn") as warn: + + parse_command_line(["-"]) + + assert {c.args[0] for c in warn.call_args_list} == expect_warn + + def test_help_description_without_isort_package(capsys): """``darker --help`` description shows how to add ``isort`` if it's not present""" with isort_present(False): From 3ca4b1968e6205dbe4d6d6c7ce9b22443a4e9507 Mon Sep 17 00:00:00 2001 From: Antti Kaihola <13725+akaihola@users.noreply.github.com> Date: Sat, 30 Mar 2024 22:58:37 +0200 Subject: [PATCH 3/6] Satisfy linters --- pyproject.toml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index 179c5bef0..57731a09c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -53,3 +53,7 @@ ignore = [ "C408", # Unnecessary `dict` call (rewrite as a literal) "S101", # Use of `assert` detected ] + +[tool.ruff.lint.isort] +known-first-party = ["darkgraylib", "graylint"] +known-third-party = ["pytest"] From 207ad2957a23cf7d8cffc14a7d20ff12fdcb08c6 Mon Sep 17 00:00:00 2001 From: Antti Kaihola <13725+akaihola@users.noreply.github.com> Date: Sat, 30 Mar 2024 23:00:51 +0200 Subject: [PATCH 4/6] Update the change log --- CHANGES.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index 00402af01..92c84fffa 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -5,11 +5,15 @@ These features will be included in the next release: Added ----- +- In the Darker configuration file under ``[tool.darker]``, the Black configuration + options ``skip_string_normalization`` and ``skip_magic_trailing_comma`` have been + deprecated and will be removed in Darker 3.0. A deprecation warning is now displayed + if they are still used. Removed ------- -The ``release_tools/update_contributors.py`` script was moved to the -``darkgray-dev-tools`` repository. +- The ``release_tools/update_contributors.py`` script was moved to the + ``darkgray-dev-tools`` repository. Fixed ----- From cf0fdb1c0ab717fad559e3caca9b391300063051 Mon Sep 17 00:00:00 2001 From: Antti Kaihola <13725+akaihola@users.noreply.github.com> Date: Sat, 13 Apr 2024 19:35:09 +0300 Subject: [PATCH 5/6] Require Graylint 1.1.1 or newer --- constraints-oldest.txt | 1 + setup.cfg | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/constraints-oldest.txt b/constraints-oldest.txt index 89ce1fe8e..c24f8f74c 100644 --- a/constraints-oldest.txt +++ b/constraints-oldest.txt @@ -11,6 +11,7 @@ flake8-2020==1.6.1 flake8-bugbear==22.1.11 flake8-comprehensions==3.7.0 flynt==0.76 +graylint==1.1.1 mypy==0.990 Pygments==2.4.0 pytest==6.2.0 diff --git a/setup.cfg b/setup.cfg index 8ba5b2a9b..ad1a40bac 100644 --- a/setup.cfg +++ b/setup.cfg @@ -30,7 +30,7 @@ install_requires = # NOTE: remember to keep `constraints-oldest.txt` in sync with these black>=22.3.0 darkgraylib~=1.2.0 - graylint~=1.0.1 + graylint~=1.1.1 toml>=0.10.0 # NOTE: remember to keep `.github/workflows/python-package.yml` in sync # with the minimum required Python version From c418fb2073d6272e35bb46370581ac584ccf9ab1 Mon Sep 17 00:00:00 2001 From: Antti Kaihola <13725+akaihola@users.noreply.github.com> Date: Sat, 13 Apr 2024 20:08:31 +0300 Subject: [PATCH 6/6] Update `--help` and REAMDE --- README.rst | 33 ++++++++++++++++++++++----------- src/darker/help.py | 4 ++-- 2 files changed, 24 insertions(+), 13 deletions(-) diff --git a/README.rst b/README.rst index ec9e1c652..de4bd3b90 100644 --- a/README.rst +++ b/README.rst @@ -367,12 +367,12 @@ The following `command line arguments`_ can also be used to modify the defaults: -S, --skip-string-normalization Don't normalize string quotes or prefixes --no-skip-string-normalization - Normalize string quotes or prefixes. This can be used to override - ``skip_string_normalization = true`` from a configuration file. + Normalize string quotes or prefixes. This can be used to override ``skip-string- + normalization = true`` from a Black configuration file. --skip-magic-trailing-comma Skip adding trailing commas to expressions that are split by comma where each element is on its own line. This includes function signatures. This can be used - to override ``skip_magic_trailing_comma = true`` from a configuration file. + to override ``skip-magic-trailing-comma = true`` from a Black configuration file. -l LENGTH, --line-length LENGTH How many characters per line to allow [default: 88] -t VERSION, --target-version VERSION @@ -380,9 +380,20 @@ The following `command line arguments`_ can also be used to modify the defaults: that should be supported by Black's output. [default: per-file auto-detection] To change default values for these options for a given project, -add a ``[tool.darker]`` or ``[tool.black]`` section to ``pyproject.toml`` in the -project's root directory, or to a different TOML file specified using the ``-c`` / -``--config`` option. For example: +add a ``[tool.darker]`` section to ``pyproject.toml`` in the project's root directory, +or to a different TOML file specified using the ``-c`` / ``--config`` option. + +You should configure invoked tools like Black_, isort_ and flynt_ +using their own configuration files. + +As an exception, the ``line-length`` and ``target-version`` options in ``[tool.darker]`` +can be used to override corresponding options for individual tools. + +Note that Black_ honors only the options listed in the below example +when called by ``darker``, because ``darker`` reads the Black configuration +and passes it on when invoking Black_ directly through its Python API. + +An example ``pyproject.toml`` configuration file: .. code-block:: toml @@ -399,13 +410,14 @@ project's root directory, or to a different TOML file specified using the ``-c`` "pylint", ] line-length = 80 # Passed to isort and Black, override their config + target-version = ["py312"] # Passed to Black, overriding its config log_level = "INFO" [tool.black] line-length = 88 # Overridden by [tool.darker] above skip-magic-trailing-comma = false skip-string-normalization = false - target-version = ["py38", "py39", "py310", "py311", "py312"] + target-version = ["py38", "py39", "py310", "py311", "py312"] # Overridden above exclude = "test_*\.py" extend_exclude = "/generated/" force_exclude = ".*\.pyi" @@ -415,10 +427,6 @@ project's root directory, or to a different TOML file specified using the ``-c`` known_third_party = ["pytest"] line_length = 88 # Overridden by [tool.darker] above -While isort_ reads all of its options from the configuration file, Black_ only honors -the ones listed above when called by ``darker``. Other tools are invoked as -subprocesses and use their configuration mechanisms unmodified. - Be careful to not use options which generate output which is unexpected for other tools. For example, VSCode only expects the reformat diff, so ``lint = [ ... ]`` can't be used with it. @@ -453,6 +461,9 @@ command line options *New in version 1.7.0:* The ``-f`` / ``--flynt`` command line option +*New in version 2.1.1:* In ``[tool.darker]``, deprecate the the Black options +``skip_string_normalization`` and ``skip_magic_trailing_comma`` + .. _Black documentation about pyproject.toml: https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-via-a-file .. _isort documentation about config files: https://timothycrosley.github.io/isort/docs/configuration/config_files/ .. _public GitHub repositories which install and run Darker: https://github.com/search?q=%2Fpip+install+.*darker%2F+path%3A%2F%5E.github%5C%2Fworkflows%5C%2F.*%2F&type=code diff --git a/src/darker/help.py b/src/darker/help.py index 8772a65eb..380681ae3 100644 --- a/src/darker/help.py +++ b/src/darker/help.py @@ -124,13 +124,13 @@ def get_extra_instruction(dependency: str) -> str: SKIP_STRING_NORMALIZATION = "Don't normalize string quotes or prefixes" NO_SKIP_STRING_NORMALIZATION = ( "Normalize string quotes or prefixes. This can be used to override" - " `skip_string_normalization = true` from a configuration file." + " `skip-string-normalization = true` from a Black configuration file." ) SKIP_MAGIC_TRAILING_COMMA = ( "Skip adding trailing commas to expressions that are split by comma" " where each element is on its own line. This includes function signatures." " This can be used to override" - " `skip_magic_trailing_comma = true` from a configuration file." + " `skip-magic-trailing-comma = true` from a Black configuration file." ) LINE_LENGTH = "How many characters per line to allow [default: 88]"