Merge pull request #578 from akaihola/config-deprecations

Deprecate `skip_*` Black options in `[tool.darker]`

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
 -----

README.rst

@@ -367,22 +367,33 @@ 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
        [py33\|py34\|py35\|py36\|py37\|py38\|py39\|py310\|py311\|py312] Python versions
        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

constraints-oldest.txt

@@ -5,11 +5,13 @@
 # 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
 flake8-comprehensions==3.7.0
 flynt==0.76
+graylint==1.1.1
 mypy==0.990
 Pygments==2.4.0
 pytest==6.2.0

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"]

setup.cfg

@@ -29,8 +29,8 @@ packages = find:
 install_requires =
     # NOTE: remember to keep `constraints-oldest.txt` in sync with these
     black>=22.3.0
-    darkgraylib~=1.1.1
-    graylint~=1.0.1
+    darkgraylib~=1.2.0
+    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

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)

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``"""
 

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]"

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):