darker 1.2.1

What?

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 and linters supported are:

• Black for code reformatting

• isort for sorting imports

• Mypy for static type checking

• Pylint for generic static checking of code

• Flake8 for style guide enforcement

New in version 1.1.0: Support for Mypy, Pylint and other linters.

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.

However, partial formatting is not supported by Black itself, for various good reasons, and it won’t be implemented either (134, 142, 245, 370, 511, 830).

This is where darker enters the stage. This tool is for those who want to do partial formatting anyway.

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.

How?

To install, use:

pip install darker

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:

  • -L mypy: do static type checking using Mypy

  • -L pylint: analyze code using Pylint

  • -L flake8: enforce the Python style guide using Flake8

New in version 1.1.0: The -L / --lint 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')

If you omit the --diff option, 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 and isort 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.

For more details, see:

• Black documentation about pyproject.toml

• isort documentation about config files

The following command line arguments can also be used to modify the defaults:

-r REVISION, --revision REVISION
                      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.

--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.

--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.
-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.
-l LINE_LENGTH, --line-length LINE_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, -S and -l command line options.

• isort is configured with -c and -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 in pyproject.toml.

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.

autocmd BufWritePost *.py silent :!darker %

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:

1. Install pre-commit in your environment (see pre-commit Installation for details).

1. Create a base pre-commit configuration:

   pre-commit sample-config >.pre-commit-config.yaml

1. Append to the created .pre-commit-config.yaml the following lines:

   -   repo: https://github.com/akaihola/darker
       rev: 1.2.1
       hooks:
       -   id: darker

1. install the Git hook scripts:

   pre-commit install

How does it work?

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.

License

BSD. See LICENSE.rst.

Prior art

• black-macchiato

• darken (deprecated in favor of Darker; thanks Carreau for inspiration!)

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

• 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)

Contributors ✨

See README.rst for the list of contributors.

This project follows the all-contributors specification. Contributions of any kind are welcome!

GitHub stars trend