From 9a5e44f25033117944e07ab4ab8ef8e7dbfec6bc Mon Sep 17 00:00:00 2001 From: Antti Kaihola <13725+akaihola@users.noreply.github.com> Date: Sun, 22 Jan 2023 18:10:15 +0200 Subject: [PATCH 1/4] Explain linter configuration in README --- README.rst | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index 5ab99cec1..f16cb7d44 100644 --- a/README.rst +++ b/README.rst @@ -280,12 +280,25 @@ instead of the last commit: $ darker --revision master . -Customizing ``darker``, Black and isort behavior -================================================ +Customizing ``darker``, Black_, isort_, flynt_ and linter behavior +================================================================== -Project-specific default options for ``darker``, Black_ and isort_ -are read from the project's ``pyproject.toml`` file in the repository root. -isort_ also looks for a few other places for configuration. +``darker`` invokes Black_ and isort_ internals directly instead of running their +binaries, so it needs to read and pass configuration options to them explicitly. +Project-specific default options for ``darker`` itself, Black_ and isort_ are read from +the project's ``pyproject.toml`` file in the repository root. isort_ does also look for +a few other places for configuration. + +Mypy_, Pylint_, Flake8_ and other compatible linters are invoked as +subprocesses by ``darker``, so normal configuration mechanisms apply for each of those +tools. Linters can also be configured on the command line, for example:: + + darker -L "mypy --strict" . + darker --lint "pylint --errors-only" . + +flynt_ (option ``-f`` / ``--flynt``) is also invoked as a subprocess, but passing +command line options to it is currently not supported. Configuration files need to be +used instead. Darker does honor exclusion options in Black configuration files when recursing directories, but the exclusions are only applied to Black reformatting. Isort and @@ -297,6 +310,7 @@ For more details, see: - `Black documentation about pyproject.toml`_ - `isort documentation about config files`_ - `public GitHub repositories which install and run Darker`_ +- `flynt documentation about configuration files`_ The following `command line arguments`_ can also be used to modify the defaults: @@ -434,6 +448,7 @@ command line options .. _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 +.. _flynt documentation about configuration files: https://github.com/ikamensh/flynt#configuration-files .. _command line arguments: https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#command-line-options Editor integration From 5861a84cc17d08cd3af6c414ed609da94b282e31 Mon Sep 17 00:00:00 2001 From: Antti Kaihola <13725+akaihola@users.noreply.github.com> Date: Sun, 22 Jan 2023 18:10:15 +0200 Subject: [PATCH 2/4] Clarify `-c` used only for Black and isort --- README.rst | 3 ++- src/darker/help.py | 5 ++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index f16cb7d44..f48810f73 100644 --- a/README.rst +++ b/README.rst @@ -343,7 +343,8 @@ The following `command line arguments`_ can also be used to modify the defaults: terminal and the ``pygments`` package is available, or if enabled by configuration. -c PATH, --config PATH - Ask ``black`` and ``isort`` to read configuration from ``PATH``. + Ask ``black`` and ``isort`` to read configuration from ``PATH``. Note that other + tools like flynt, Mypy, Pylint and Flake8 won't use this configuration file. -v, --verbose Show steps taken and summarize modifications -q, --quiet diff --git a/src/darker/help.py b/src/darker/help.py index 6452d59c6..850b46d70 100644 --- a/src/darker/help.py +++ b/src/darker/help.py @@ -100,7 +100,10 @@ def get_extra_instruction(dependency: str) -> str: " configuration." ) -CONFIG = "Ask `black` and `isort` to read configuration from `PATH`." +CONFIG = ( + "Ask `black` and `isort` to read configuration from `PATH`. Note that other tools" + " like flynt, Mypy, Pylint and Flake8 won't use this configuration file." +) VERBOSE = "Show steps taken and summarize modifications" QUIET = "Reduce amount of output" From 1c63e28f01cf6c97f88b951979d474f841c36af4 Mon Sep 17 00:00:00 2001 From: Antti Kaihola <13725+akaihola@users.noreply.github.com> Date: Sun, 22 Jan 2023 18:10:15 +0200 Subject: [PATCH 3/4] Clarify linter configuration in `--help` --- README.rst | 9 +++++---- src/darker/help.py | 9 +++++---- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index f48810f73..3c2ace819 100644 --- a/README.rst +++ b/README.rst @@ -338,10 +338,11 @@ The following `command line arguments`_ can also be used to modify the defaults: -i, --isort Also sort imports using the ``isort`` package -L CMD, --lint CMD - Also run a linter on changed files. ``CMD`` can be a name of path of the linter - binary, or a full quoted command line. Highlight linter output syntax if on a - terminal and the ``pygments`` package is available, or if enabled by - configuration. + Also run a linter on changed files. ``CMD`` can be a name or path of the linter + binary, or a full quoted command line with the command and options. Linters read + their configuration as normally, and aren't affected by ``-c`` / ``--config``. + Linter output is syntax highlighted when the ``pygments`` package is available if + run on a terminal and or enabled by explicitly (see ``--color``). -c PATH, --config PATH Ask ``black`` and ``isort`` to read configuration from ``PATH``. Note that other tools like flynt, Mypy, Pylint and Flake8 won't use this configuration file. diff --git a/src/darker/help.py b/src/darker/help.py index 850b46d70..62de3a50a 100644 --- a/src/darker/help.py +++ b/src/darker/help.py @@ -94,10 +94,11 @@ def get_extra_instruction(dependency: str) -> str: ISORT = "".join(ISORT_PARTS) LINT = ( - "Also run a linter on changed files. `CMD` can be a name of path of the" - " linter binary, or a full quoted command line. Highlight linter output syntax if" - " on a terminal and the `pygments` package is available, or if enabled by" - " configuration." + "Also run a linter on changed files. `CMD` can be a name or path of the linter" + " binary, or a full quoted command line with the command and options. Linters read" + " their configuration as normally, and aren't affected by `-c` / `--config`. Linter" + " output is syntax highlighted when the `pygments` package is available if run on" + " a terminal and or enabled by explicitly (see `--color`)." ) CONFIG = ( From a6c7dc5fa72ad6b6c2ada860e9dc0ca3a167238e Mon Sep 17 00:00:00 2001 From: Antti Kaihola <13725+akaihola@users.noreply.github.com> Date: Sun, 22 Jan 2023 18:10:15 +0200 Subject: [PATCH 4/4] Update the change log --- CHANGES.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES.rst b/CHANGES.rst index 1a8ef8288..7031e7054 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -44,6 +44,7 @@ Added - Document how to set up a development environment, run tests, run linters and update contributors list in ``CONTRIBUTING.rst``. - Document how to pin reformatter/linter versions in ``pre-commit``. +- Clarify configuration of reformatter/linter tools in README and ``--help``. Fixed -----