Darker – reformat modified Python code
|build-badge| |license-badge| |pypi-badge| |downloads-badge| |black-badge| |changelog-badge|
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.
The reformatters supported are:
Black_ for code reformatting
isort_ for sorting imports
flynt_ for turning old-style format strings to f-strings
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.
We’re asking the community kindly for help to review pull requests for |next-milestone|_ . If you have a moment to spare, please take a look at one of them and shoot us a comment! |
We have a `community support channel`_ on GitHub Discussions. Welcome to ask for help and advice! |
New in version 1.4.0: Darker can be used in plain directories, not only Git repositories.
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.
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.”
How?
To install or upgrade, use:
pip install --upgrade darker[black]~=2.1.1
Or, if you’re using Conda_ for package management:
conda install -c conda-forge darker~=2.1.1 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 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 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 theflyntpackage
If you only want to run those tools without reformatting with Black,
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.
Example
This example walks you through a minimal practical use case for Darker.
First, create an empty Git repository:
$ 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:
if True: print('hi')
print()
if False: print('there')
Commit that file:
$ 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:
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:
$ 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):
$ darker --stdout our_file.py
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:
$ 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!
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:
$ darker .
Or, if you want to compare to another branch (or, in fact, any commit) instead of the last commit:
$ darker --revision master .
Customizing darker, Black_, isort_ and flynt_ 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.
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 is 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:
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 likeHEAD~5work here. Also a range likemain...HEADormain...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 thePRE_COMMIT_FROM_REFandPRE_COMMIT_TO_REFenvironment variables. If those are not found, Darker works againstHEAD. 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-filenameis enabled).- -c PATH, --config PATH
Make
darker,blackandisortread configuration fromPATH. Note that other tools likeflyntwon’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
0for 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
pygmentspackage 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
pygmentspackage 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
flyntpackage- -i, --isort
Also sort imports using the
isortpackage- --preview
In Black, enable potentially disruptive style changes that may be added to Black in the future
- -L CMD, --lint CMD
Show information about baseline linting using the Graylint package.
- -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 = truefrom 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 = truefrom 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]
- --formatter FORMATTER
[black|none|pyupgrade|ruff] Formatter to use for reformatting code. [default: black]
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 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:
[tool.darker]
src = [
"src/mypackage",
]
revision = "master"
diff = true
check = true
isort = true
flynt = true
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 = ["py39", "py310", "py311", "py312"] # Overridden above
exclude = "test_*\.py"
extend_exclude = "/generated/"
force_exclude = ".*\.pyi"
preview = true # Only supported in [tool.black]
[tool.isort]
profile = "black"
known_third_party = ["pytest"]
line_length = 88 # Overridden by [tool.darker] above
New in version 1.0.0:
The
-c,-Sand-lcommand line options.isort_ is configured with
-cand-l, too.
New in version 1.1.0: The command line options
-r/--revision--diff--check--no-skip-string-normalization-L/--lint
New in version 1.2.0: Support for
commit ranges in
-r/--revision.a
[tool.darker]section inpyproject.toml.
New in version 1.2.2: Support for -r :PRE-COMMIT: / --revision=:PRE_COMMIT:
New in version 1.3.0: The --skip-magic-trailing-comma and -d / --stdout
command line options
New in version 1.5.0: The -W / --workers, --color and --no-color
command line options
New in version 1.7.0: The -t / --target-version command line option
New in version 1.7.0: The -f / --flynt command line option
New in version 3.0.0: In [tool.darker], remove the the Black options
skip_string_normalization and skip_magic_trailing_comma (previously deprecated
in version 2.1.1)
New in version 3.0.0: Removed the -L / --lint functionality and moved it into
the Graylint_ package. Also removed lint =, skip_string_normalization = and
skip_magic_trailing_comma = from [tool.darker].
Editor integration
Many editors have plugins or recipes for integrating Black_.
You may be able to adapt them to be used with darker.
See editor integration in the Black_ documentation.
PyCharm/IntelliJ IDEA
Install
darker:$ pip install 'darker[black]'
Locate your
darkerinstallation folder.On macOS / Linux / BSD:
$ which darker /usr/local/bin/darker # possible location
On Windows:
$ where darker %LocalAppData%\Programs\Python\Python36-32\Scripts\darker.exe # possible location
Open External tools in PyCharm/IntelliJ IDEA
On macOS:
PyCharm -> Preferences -> Tools -> External ToolsOn Windows / Linux / BSD:
File -> Settings -> Tools -> External Tools
Click the
+icon to add a new external tool with the following values:Name: Darker
Description: Use Black to auto-format regions changed since the last git commit.
Program: <install_location_from_step_2>
Arguments:
"$FilePath$"
If you need any extra command line arguments like the ones which change Black behavior, you can add them to the
Argumentsfield, e.g.:--config /home/myself/black.cfg "$FilePath$"
You can now format the currently opened file by selecting
Tools -> External Tools -> Darkeror right clicking on a file and selectingExternal Tools -> DarkerOptionally, set up a keyboard shortcut at
Preferences or Settings -> Keymap -> External Tools -> External Tools - DarkerOptionally, run
darkeron every file save:Make sure you have the File Watcher plugin installed.
Go to
Preferences or Settings -> Tools -> File Watchersand click+to add a new watcher:Name: Darker
File type: Python
Scope: Project Files
Program: <install_location_from_step_2>
Arguments:
$FilePath$Output paths to refresh:
$FilePath$Working directory:
$ProjectFileDir$
Uncheck “Auto-save edited files to trigger the watcher”
Visual Studio Code
Install
darker:$ pip install 'darker[black]'
Locate your
darkerinstallation folder.On macOS / Linux / BSD:
$ which darker /usr/local/bin/darker # possible location
On Windows:
$ where darker %LocalAppData%\Programs\Python\Python36-32\Scripts\darker.exe # possible location
Make sure you have the VSCode black-formatter extension installed.
Add these configuration options to VSCode (
⌘ Command / Ctrl+⇧ Shift+Pand selectOpen Settings (JSON)):"python.editor.defaultFormatter": "ms-python.black-formatter", "black-formatter.path": "<install_location_from_step_2>", "black-formatter.args": ["-d"],
VSCode will always add --diff --quiet as arguments to Darker,
but you can also pass additional arguments in the black-formatter.args option
(e.g. ["-d", "--isort", "--revision=master..."]).
Note that VSCode first copies the file to reformat into a temporary
<filename>.py.<hash>.tmp file, then calls Black (or Darker in this case) on that
file, and brings the changes in the modified files back into the editor.
Darker is aware of this behavior, and will correctly compare .py.<hash>.tmp files
to corresponding .py files from earlier repository revisions.
Vim
Unlike Black_ and many other formatters, darker needs access to the Git history.
Therefore it does not work properly with classical auto reformat plugins.
You can though ask vim to run darker on file save with the following in your
.vimrc:
set autoread
autocmd BufWritePost *.py silent :!darker %
BufWritePostto rundarkeronce the file has been saved,silentto not ask for confirmation each time,:!to run an external command,%for current file name.
Vim should automatically reload the file.
Emacs
You can integrate with Emacs using Steve Purcell’s emacs-reformatter library.
Using use-package:
(use-package reformatter
:hook ((python-mode . darker-reformat-on-save-mode))
:config
(reformatter-define darker-reformat
:program "darker"
:stdin nil
:stdout nil
:args (list "-q" input-file))
This will automatically reformat the buffer on save.
You have multiple functions available to launch it manually:
darker-reformat
darker-reformat-region
darker-reformat-buffer
Using as a pre-commit hook
New in version 1.2.1
To use Darker locally as a Git pre-commit hook for a Python project, do the following:
Install pre-commit_ in your environment (see `pre-commit Installation`_ for details).
Create a base pre-commit configuration:
pre-commit sample-config >.pre-commit-config.yaml
Append to the created
.pre-commit-config.yamlthe following lines:- repo: https://github.com/akaihola/darker rev: v2.1.1 hooks: - id: darker
install the Git hook scripts and update to the newest version:
pre-commit install pre-commit autoupdate
When auto-updating, care is being taken to protect you from possible incompatibilities introduced by Black updates. See `Guarding against Black compatibility breakage`_ for more information.
If you’d prefer to not update but keep a stable pre-commit setup, you can pin Black and other reformatter tools you use to known compatible versions, for example:
- repo: https://github.com/akaihola/darker
rev: v2.1.1
hooks:
- id: darker
args:
- --isort
additional_dependencies:
- black==22.12.0
- isort==5.11.4
Using arguments
You can provide arguments, such as disabling Darker or enabling isort,
by specifying args.
Note the absence of Black and the inclusion of the isort Python package
under additional_dependencies:
- repo: https://github.com/akaihola/darker
rev: v2.1.1
hooks:
- id: darker
args:
- --formatter=none
- --isort
additional_dependencies:
- isort~=5.9
GitHub Actions integration
You can use Darker within a GitHub Actions workflow without setting your own Python environment. Great for enforcing that modifications and additions to your code match the Black_ code style.
Compatibility
This action is known to support all GitHub-hosted runner OSes. In addition, only published versions of Darker are supported (i.e. whatever is available on PyPI). You can `search workflows in public GitHub repositories`_ to see how Darker is being used.
Usage
Create a file named .github/workflows/darker.yml inside your repository with:
name: Reformat
on: [push, pull_request]
jobs:
reformat:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-python@v5
- uses: akaihola/darker@2.1.1
with:
options: "--check --diff --isort --color"
src: "./src"
version: "~=2.1.1"
There needs to be a working Python environment, set up using actions/setup-python
in the above example. Darker will be installed in an isolated virtualenv to prevent
conflicts with other workflows.
"uses:" specifies which Darker release to get the GitHub Action definition from.
We recommend to pin this to a specific release.
"version:" specifies which version of Darker to run in the GitHub Action.
It defaults to the same version as in "uses:",
but you can force it to use a different version as well.
Darker versions available from PyPI are supported, as well as commit SHAs or branch
names, prefixed with an @ symbol (e.g. version: "@master").
The revision: "master..." (or "main...") option instructs Darker
to compare the current branch to the branching point from main branch
when determining which source code lines have been changed.
If omitted, the Darker GitHub Action will determine the commit range automatically.
"src:" defines the root directory to run Darker for.
This is typically the source tree, but you can use "." (the default)
to also reformat Python files like "setup.py" in the root of the whole repository.
You can also configure other arguments passed to Darker via "options:".
It defaults to "--check --diff --color".
You can e.g. add "--isort" to sort imports, or "--verbose" for debug logging.
New in version 1.1.0: GitHub Actions integration. Modeled after how Black_ does it, thanks to Black authors for the example!
New in version 1.4.1:
The revision: option, with smart default value if omitted.
New in version 1.5.0:
The lint: option.
New in version 3.0.0:
Removed the lint: option and moved it into the GitHub action
of the Graylint_ package.
New in version 3.0.0: Black is now explicitly installed when running the action.
Syntax highlighting
Darker automatically enables syntax highlighting for the --diff and
-d/--stdout options if it’s running on a terminal and the
Pygments_ package is installed.
You can force enable syntax highlighting on non-terminal output using
the
color = trueoption in the[tool.darker]section ofpyproject.tomlof your Python project’s root directory,the
PY_COLORS=1environment variable, andthe
--colorcommand line option fordarker.
You can force disable syntax highlighting on terminal output using
the
color = falseoption inpyproject.toml,the
PY_COLORS=0environment variable, andthe
--no-colorcommand line option.
In the above lists, latter configuration methods override earlier ones, so the command line options always take highest precedence.
Guarding against Black compatibility breakage
Darker accesses some Black internals which don’t belong to its public API. Darker is thus subject to becoming incompatible with future versions of Black.
To protect users against such breakage, we test Darker daily against the `Black main
branch`_ and strive to proactively fix any potential incompatibilities through this
process. If a commit to Black main branch introduces an incompatibility with
Darker, we will release a first patch version for Darker that prevents upgrading Black
and a second patch version that fixes the incompatibility. A hypothetical example:
Darker 9.0.0; Black 35.12.0 -> OK
Darker 9.0.0; Black
main(after 35.12.0) -> ERROR on CI test-future_ workflowDarker 9.0.1 released, with constraint
Black<=35.12.0-> OKBlack 36.1.0 released, but Darker 9.0.1 prevents upgrade; Black 35.12.0 -> OK
Darker 9.0.2 released with a compatibility fix, constraint removed; Black 36.1.0 -> OK
If a Black release introduces an incompatibility before the second Darker patch version that fixes it, the first Darker patch version will downgrade Black to the latest compatible version:
Darker 9.0.0; Black 35.12.0 -> OK
Darker 9.0.0; Black 36.1.0 -> ERROR
Darker 9.0.1, constraint
Black<=35.12.0; downgrades to Black 35.12.0 -> OKDarker 9.0.2 released with a compatibility fix, constraint removed; Black 36.1.0 -> OK
To be completely safe, you can pin both Darker and Black to known good versions, but this may prevent you from receiving improvements in Black.
It is recommended to use the ‘~=’ “`compatible release`_” version specifier for
Darker to ensure you have the latest version before the next major release that may
cause compatibility issues.
How does it work?
To apply Black reformatting and to modernize format strings on changed lines, Darker does the following:
take a
git diffof Python files betweenREV1andREV2as specified using the--revision=REV1..REV2optionrecord current line numbers of lines edited or added between those revisions
run flynt_ on edited and added files (if Flynt is enabled by the user)
run Black_ on edited and added files
compare before and after reformat, noting each continuous chunk of reformatted lines
discard reformatted chunks on which no edited/added line falls on
keep reformatted chunks on which some edited/added lines fall on
To sort imports when the --isort option was specified, Darker proceeds like this:
run isort_ on each edited and added file before applying Black_
only if any of the edited or added lines falls between the first and last line modified by isort_, are those modifications kept
if all lines between the first and last line modified by isort_ were unchanged between the revisions, discard import sorting modifications for that file
Limitations and work-arounds
Black doesn’t support partial formatting natively. Because of this, Darker lets Black reformat complete files. Darker then accepts or rejects chunks of contiguous lines touched by Black, depending on whether any of the lines in a chunk were edited or added between the two revisions.
Due to the nature of this algorithm, Darker is often unable to minimize the number of changes made by Black as carefully as a developer could do by hand. Also, depending on what kind of changes were made to the code, diff results may lead to Darker applying reformatting in an invalid way. Fortunately, Darker always checks that the result of reformatting converts to the same AST as the original code. If that’s not the case, Darker expands the chunk until it finds a valid reformatting. As a result, a much larger block of code may be reformatted than necessary.
The most reasonable work-around to these limitations is to review the changes made by Darker before committing them to the repository and unstaging any changes that are not desired.
License
BSD. See LICENSE.rst.
Prior art
Interesting code formatting and analysis projects to watch
The following projects are related to Black_ or Darker in some way or another. Some of them we might want to integrate to be part of a Darker run.
blacken-docs – Run Black_ on Python code blocks in documentation files
velin – Reformat docstrings that follow the numpydoc convention
diff-cov-lint – Pylint and coverage reports for git diff only
xenon – Monitor code complexity
pyupgrade – Upgrade syntax for newer versions of the language (see `#51`_)
yapf_ – Google’s Python formatter
yapf_diff – apply yapf_ or other formatters to modified lines only
Contributors ✨
Thanks goes to these wonderful people (`emoji key`_):
This project follows the all-contributors_ specification. Contributions of any kind are welcome!