This utility reformats and checks Python source code files in a Git repository. However, it only applies reformatting and reports errors in regions which have changed in the Git working tree since the last commit.
The reformatters supported are:
See Using linters below for the list of supported linters.
 |
 |
|---|---|
We're asking the community kindly for help to
review pull requests for  .
If you have a moment to spare, please take a
look at one of them and shoot us a comment! |
We're considering to start a community support chat channel. Please vote for your preferred medium in issue #151! |
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.
To install, use:
pip install darker
Or, if you're using Conda for package management:
conda install -c conda-forge darker isort
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-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.
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.pyNow 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.pyNow 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 .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 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:
The following command line arguments can also be used to modify the defaults:
| -r REV, --revision REV | |
Git revision against which to compare the working tree. Tags, branch names,
commit hashes, and other expressions like HEAD~5 work here. Also a range like
master...HEAD or master... 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. | |
| --diff | Don't write the files back, just output a diff for each file on stdout. Highlight
syntax on screen if the pygments package is available. |
| -d, --stdout | Force complete reformatted output to stdout, instead of in-place. Only valid if there's just one file to reformat. |
| --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. |
| -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 | |
| -c PATH, --config PATH | |
Ask black and isort to read configuration from PATH. | |
| -v, --verbose | Show steps taken and summarize modifications |
| -q, --quiet | Reduce amount of output |
| -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. | |
| --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. | |
| -l LENGTH, --line-length LENGTH | |
| How many characters per line to allow [default: 88] | |
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.
For example:
[tool.darker]
src = [
"src/mypackage",
]
revision = "master"
diff = true
check = true
isort = true
lint = [
"pylint",
]
log_level = "INFO"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: Support for command line option --skip-magic-trailing-comma
New in version 1.3.0: The -d / --stdout command line option
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.
Install
darker:$ pip install darker
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 ToolsClick 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$"
Format the currently opened file by selecting
Tools -> External Tools -> Darker.- Alternatively, you can set a keyboard shortcut by navigating to
Preferences or Settings -> Keymap -> External Tools -> External Tools - Darker
- Alternatively, you can set a keyboard shortcut by navigating to
Optionally, 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"
Install
darker:$ pip install darker
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
Add these configuration options to VS code,
Cmd-Shift-P,Open Settings (JSON):"python.formatting.provider": "black", "python.formatting.blackPath": "<install_location_from_step_2>", "python.formatting.blackArgs": ["--diff"],
You can pass additional arguments to darker in the blackArgs option
(e.g. ["--diff", "--isort"]), but make sure at least --diff is included.
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.
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.
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: 1.3.2 hooks: - id: darkerinstall the Git hook scripts:
pre-commit install
You can provide arguments, such as enabling isort, by specifying args.
Note the inclusion of the isort Python package under additional_dependencies:
- repo: https://github.com/akaihola/darker
rev: 1.3.2
hooks:
- id: darker
args: [--isort]
additional_dependencies:
- isort~=5.9
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.
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).
Create a file named .github/workflows/darker.yml inside your repository with:
name: Lint
on: [push, pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0
- uses: akaihola/[email protected]We recommend the use per version tags.
The version of Darker the action will use can be configured via version.
The action defaults to the action's version tag.
Only versions available from PyPI are supported, so no commit SHAs or branch names.
You can also configure the arguments passed to Darker via options
(defaults to '--check --diff') and src (default is '.').
Here's an example configuration:
- uses: akaihola/[email protected]
with:
options: "--check --verbose"
src: "./src"
version: "1.3.2"New in version 1.1.0: GitHub Actions integration. Modeled after how Black does it, thanks to Black authors for the example!
One way to use Darker is to filter linter output to modified lines only. Darker supports any linter with output in one of the following formats:
<file>:<linenum>: <description> <file>:<linenum>:<col>: <description>
Most notably, the following linters/checkers have been verified to work with Darker:
- Mypy for static type checking
- Pylint for generic static checking of code
- Flake8 for style guide enforcement
- cov_to_lint.py for test coverage
New in version 1.1.0: Support for Mypy, Pylint, Flake8 and compatible linters.
New in version 1.2.0: Support for test coverage output using cov_to_lint.py.
To run a linter, use the --lint / -L command line option:
Darker also groups linter output into blocks of consecutive lines separated by blank lines. Here's an example of cov_to_lint.py output:
$ darker --revision 0.1.0.. --check --lint cov_to_lint.py src
src/darker/__main__.py:94: no coverage: logger.debug("No changes in %s after isort", src)
src/darker/__main__.py:95: no coverage: break
src/darker/__main__.py:125: no coverage: except NotEquivalentError:
src/darker/__main__.py:130: no coverage: if context_lines == max_context_lines:
src/darker/__main__.py:131: no coverage: raise
src/darker/__main__.py:132: no coverage: logger.debug(
Darker takes a git diff of your Python files,
records which lines of current files have been edited or added since the last commit.
It then runs Black and notes which chunks of lines were reformatted.
Finally, only those reformatted chunks on which edited lines fall (even partially)
are applied to the edited file.
Also, in case the --isort option was specified,
isort is run on each edited file before applying Black.
Similarly, each linter requested using the --lint <command> option is run,
and only linting errors/warnings on modified lines are displayed.
BSD. See LICENSE.rst.
- black-macchiato
- darken (deprecated in favor of Darker; thanks Carreau for inspiration!)
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
- blackdoc – Run Black on documentation code snippets
- 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
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind are welcome!
