======================================== Darker – reformat modified Python code

|build-badge| |license-badge| |pypi-badge| |downloads-badge| |black-badge| |changelog-badge|

.. |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%203.0.1 :alt: Next milestone :target: https://github.com/akaihola/darker/milestone/24

What?

This utility reformats 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.

The reformatters supported are:

• Black_ and the Ruff formatter_ for code reformatting
• isort_ for sorting imports
• flynt_ for turning old-style format strings to f-strings
• pyupgrade_ for upgrading syntax for newer versions of Python

NOTE: Baseline linting support has been moved to the Graylint_ package.

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://black.readthedocs.io/ .. _the Ruff formatter: https://docs.astral.sh/ruff/formatter/ .. _isort: https://pycqa.github.io/isort/ .. _flynt: https://github.com/ikamensh/flynt .. _pyupgrade: https://github.com/asottile/pyupgrade .. _Pytest: https://docs.pytest.org/ .. _pytest-darker: https://pypi.org/project/pytest-darker/

+------------------------------------------------+--------------------------------+ | |you-can-help| | |support| | +================================================+================================+ | We're asking the community kindly for help to | We have a | | review pull requests for |next-milestone|_ . | community support channel_ | | If you have a moment to spare, please take a | on GitHub Discussions. Welcome | | look at one of them and shoot us a comment! | to ask for help and advice! | +------------------------------------------------+--------------------------------+

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_ or the Ruff formatter_. Maybe you also like to standardize on how to order your imports, or convert string formatting to use f-strings.

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 was not supported by Black_ itself when Darker was originally created, which is why Darker was developed to provide this functionality. However, Black has since added the -\-line-ranges_ command line option for partial formatting, which could potentially simplify Darker's implementation.

.. _--line-ranges: https://black.readthedocs.io/en/latest/usage_and_configuration/the_basics.html#line-ranges

The --range option in the Ruff formatter_ allows for partial formatting of a single range as well, but to make use of it, Darker would need call the Ruff formatter_ once for each modified chunk.

However, Black doesn't help in determining which line ranges to format. This is where darker enters the stage. This tool is for those who want to do partial formatting for modified parts of the code.

Note that this tool is meant for special situations when dealing with existing code bases. You should just use Black_ or the Ruff formatter, Flynt 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~=3.0.0

To also install support for Black_ formatting::

pip install --upgrade 'darker[black]~=3.0.0'

To install support for all available formatting and analysis tools::

pip install --upgrade 'darker[color,black,ruff,isort,flynt,pyupgrade]~=3.0.0'

The available optional dependencies are:

• color: Enable syntax highlighting in terminal output using Pygments_
• black: Enable Black_ code formatting (the default formatter)
• ruff: Enable code formatting using the Ruff formatter_
• isort: Enable isort_ import sorting
• flynt: Enable flynt_ string formatting conversion
• pyupgrade: Enable pyupgrade_ code upgrades

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

conda install -c conda-forge darker~=3.0.0 black isort conda update -c conda-forge darker

..

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

New in version 3.0.0: Black is no longer installed by default.

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 uses Black_ to reformat the code. You can choose different formatters or enable additional features with command line options:

• --formatter=black: Use Black_ for code formatting (the default)
• --formatter=ruff: Use the Ruff formatter_ instead of Black_.
• --formatter=pyupgrade: Use pyupgrade_ to upgrade Python syntax
• --formatter=none: Don't run any formatter, only run other enabled tools
• -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

If you only want to run isort_ and/or Flynt_ without reformatting code, use the --formatter=none option.

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

New in version 3.0.0: Removed the -L / --lint functionality and moved it into the Graylint_ package.

New in version 3.0.0: The --formatter 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