================================================= Darker – reformat and lint modified Python code

.. |build-badge| image:: https://github.com/akaihola/darker/actions/workflows/python-package.yml/badge.svg :alt: master branch build status :target: https://github.com/akaihola/darker/actions/workflows/python-package.yml?query=branch%3Amaster .. |license-badge| image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg :alt: BSD 3 Clause license :target: https://github.com/akaihola/darker/blob/master/LICENSE.rst .. |pypi-badge| image:: https://img.shields.io/pypi/v/darker :alt: Latest release on PyPI :target: https://pypi.org/project/darker/ .. |downloads-badge| image:: https://pepy.tech/badge/darker :alt: Number of downloads :target: https://pepy.tech/project/darker .. |black-badge| image:: https://img.shields.io/badge/code%20style-black-000000.svg :alt: Source code formatted using Black :target: https://github.com/psf/black .. |changelog-badge| image:: https://img.shields.io/badge/-change%20log-purple :alt: Change log :target: https://github.com/akaihola/darker/blob/master/CHANGES.rst .. |next-milestone| image:: https://img.shields.io/github/milestones/progress/akaihola/darker/25?color=red&label=release%202.1.2 :alt: Next milestone :target: https://github.com/akaihola/darker/milestone/24

What?

This utility reformats and checks Python source code files. However, when run in a Git repository, it compares an old revision of the source tree to a newer revision (or the working tree). It then

only applies reformatting in regions which have changed in the Git working tree between the two revisions, and
only reports those linting messages which appeared after the modifications to the source code files.

The reformatters supported are:

Black_ for code reformatting
isort_ for sorting imports
flynt_ for turning old-style format strings to f-strings

See Using linters_ below for the list of supported linters.

To easily run Darker as a Pytest_ plugin, see pytest-darker_.

To integrate Darker with your IDE or with pre-commit_, see the relevant sections below in this document.

.. _Black: https://github.com/python/black .. _isort: https://github.com/timothycrosley/isort .. _flynt: https://github.com/ikamensh/flynt .. _Pytest: https://docs.pytest.org/ .. _pytest-darker: https://pypi.org/project/pytest-darker/

New in version 1.4.0: Darker can be used in plain directories, not only Git repositories.

.. |you-can-help| image:: https://img.shields.io/badge/-You%20can%20help-green?style=for-the-badge :alt: You can help .. |support| image:: https://img.shields.io/badge/-Support-green?style=for-the-badge :alt: Support .. _#151: https://github.com/akaihola/darker/issues/151 .. _community support channel: https://github.com/akaihola/darker/discussions

Why?

You want to start unifying code style in your project using Black_. Maybe you also like to standardize on how to order your imports, or do static type checking or other static analysis for your code.

However, instead of formatting the whole code base in one giant commit, you'd like to only change formatting when you're touching the code for other reasons.

This can also be useful when contributing to upstream codebases that are not under your complete control.

Partial formatting is not supported by Black_ itself, for various good reasons, and so far there hasn't been a plan to implemented it either (134, 142, 245, 370, 511, 830). However, in September 2021 Black developers started to hint towards adding this feature after all (1352__). This might at least simplify Darker's algorithm substantially.

__ https://github.com/psf/black/issues/134 __ https://github.com/psf/black/issues/142 __ https://github.com/psf/black/issues/245 __ https://github.com/psf/black/issues/370 __ https://github.com/psf/black/issues/511 __ https://github.com/psf/black/issues/830 __ https://github.com/psf/black/issues/1352

But for the time being, this is where darker enters the stage. This tool is for those who want to do partial formatting right now.

Note that this tool is meant for special situations when dealing with existing code bases. You should just use Black_ and isort_ as is when starting a project from scratch.

You may also want to still consider whether reformatting the whole code base in one commit would make sense in your particular case. You can ignore a reformatting commit in git blame using the blame.ignoreRevsFile_ config option or --ignore-rev on the command line. For a deeper dive into this topic, see Avoiding ruining git blame_ in Black documentation, or the article Why does Black insist on reformatting my entire project?_ from Łukasz Langa_ (@ambv_, the creator of Black). Here's an excerpt:

"When you make this single reformatting commit, everything that comes after is
**semantic changes** so your commit history is clean in the sense that it actually
shows what changed in terms of meaning, not style. There are tools like darker that
allow you to only reformat lines that were touched since the last commit. However,
by doing that you forever expose yourself to commits that are a mix of semantic
changes with stylistic changes, making it much harder to see what changed."

.. _blame.ignoreRevsFile: https://git-scm.com/docs/git-blame/en#Documentation/git-blame.txt---ignore-revs-fileltfilegt .. _Avoiding ruining git blame: https://black.readthedocs.io/en/stable/guides/introducing_black_to_your_project.html#avoiding-ruining-git-blame .. _Why does Black insist on reformatting my entire project?: https://lukasz.langa.pl/36380f86-6d28-4a55-962e-91c2c959db7a/ .. _Łukasz Langa: https://lukasz.langa.pl/ .. _@ambv: https://github.com/ambv

How?

To install or upgrade, use::

pip install --upgrade darker~=2.1.1

Or, if you're using Conda_ for package management::

conda install -c conda-forge darker~=2.1.1 isort conda update -c conda-forge darker

**Note:** It is recommended to use the '``~=``' "`compatible release`_" version
specifier for Darker. See `Guarding against Black compatibility breakage`_ for more
information.

The darker <myfile.py> or darker <directory> command reads the original file(s), formats them using Black_, combines original and formatted regions based on edits, and writes back over the original file(s).

Alternatively, you can invoke the module directly through the python executable, which may be preferable depending on your setup. Use python -m darker instead of darker in that case.

By default, darker just runs Black_ to reformat the code. You can enable additional features with command line options:

-i / --isort: Reorder imports using isort_. Note that isort_ must be run in the same Python environment as the packages to process, as it imports your modules to determine whether they are first or third party modules.
-f / --flynt: Also convert string formatting to use f-strings using the flynt package
-L <linter> / --lint <linter>: Run a supported linter (see Using linters_)

New in version 1.1.0: The -L / --lint option. New in version 1.2.2: Package available in conda-forge_. New in version 1.7.0: The -f / --flynt option

.. _Conda: https://conda.io/ .. _conda-forge: https://conda-forge.org/

Example

This example walks you through a minimal practical use case for Darker.

First, create an empty Git repository:

.. code-block:: shell

$ mkdir /tmp/test $ cd /tmp/test $ git init Initialized empty Git repository in /tmp/test/.git/

In the root of that directory, create the ill-formatted Python file our_file.py:

.. code-block:: python

if True: print('hi') print() if False: print('there')

Commit that file:

.. code-block:: shell

$ git add our_file.py $ git commit -m "Initial commit" [master (root-commit) a0c7c32] Initial commit 1 file changed, 3 insertions(+) create mode 100644 our_file.py

Now modify the first line in that file:

.. code-block:: python

if True: print('CHANGED TEXT') print() if False: print('there')

You can ask Darker to show the diff for minimal reformatting which makes edited lines conform to Black rules:

.. code-block:: diff

$ darker --diff our_file.py --- our_file.py +++ our_file.py @@ -1,3 +1,4 @@ -if True: print('CHANGED TEXT') +if True:

print("CHANGED TEXT") print() if False: print('there')

Alternatively, Darker can output the full reformatted file (works only when a single Python file is provided on the command line):

.. code-block:: shell

$ darker --stdout our_file.py

.. code-block:: python

if True: print("CHANGED TEXT") print() if False: print('there')

If you omit the --diff and --stdout options, Darker replaces the files listed on the command line with partially reformatted ones as shown above:

.. code-block:: shell

$ darker our_file.py

Now the contents of our_file.py will have changed. Note that the original print() and if False: ... lines have not been reformatted since they had not been edited!

.. code-block:: python

if True: print("CHANGED TEXT") print() if False: print('there')

You can also ask Darker to reformat edited lines in all Python files in the repository:

.. code-block:: shell

$ darker .

Or, if you want to compare to another branch (or, in fact, any commit) instead of the last commit:

.. code-block:: shell

$ darker --revision master .

Customizing `darker`, Black_, isort_, flynt_ and linter behavior

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 linters are still run on excluded files. Also, individual files explicitly listed on the command line are still reformatted even if they match exclusion patterns.

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:

-r REV, --revision REV Revisions to compare. The default is HEAD..:WORKTREE: which compares the latest commit to the working tree. Tags, branch names, commit hashes, and other expressions like HEAD~5 work here. Also a range like main...HEAD or main... can be used to compare the best common ancestor. With the magic value :PRE-COMMIT:, Darker works in pre-commit compatible mode. Darker expects the revision range from the PRE_COMMIT_FROM_REF and PRE_COMMIT_TO_REF environment variables. If those are not found, Darker works against HEAD. Also see --stdin-filename= for the :STDIN: special value. --stdin-filename PATH The path to the file when passing it through stdin. Useful so Darker can find the previous version from Git. Only valid with --revision=<rev1>..:STDIN: (HEAD..:STDIN: being the default if --stdin-filename is enabled). -c PATH, --config PATH Make darker, black and isort read configuration from PATH. Note that other tools like flynt, mypy, pylint or flake8 won't use this configuration file. -v, --verbose Show steps taken and summarize modifications -q, --quiet Reduce amount of output --color Enable syntax highlighting even for non-terminal output. Overrides the environment variable PY_COLORS=0 --no-color Disable syntax highlighting even for terminal output. Overrides the environment variable PY_COLORS=1 -W WORKERS, --workers WORKERS How many parallel workers to allow, or 0 for one per core [default: 1] --diff Don't write the files back, just output a diff for each file on stdout. Highlight syntax if on a terminal and the pygments package is available, or if enabled by configuration. -d, --stdout Force complete reformatted output to stdout, instead of in-place. Only valid if there's just one file to reformat. Highlight syntax if on a terminal and the pygments package is available, or if enabled by configuration. --check Don't write the files back, just return the status. Return code 0 means nothing would change. Return code 1 means some files would be reformatted. -f, --flynt Also convert string formatting to use f-strings using the flynt package -i, --isort Also sort imports using the isort package -L CMD, --lint CMD 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). -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 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 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|py313] 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] 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