Skip to content
forked from akaihola/darker

Apply black reformatting to Python files only in regions changed since a given commit. For a practical usage example, see the blog post at https://dev.to/akaihola/improving-python-code-incrementally-3f7a

License

Notifications You must be signed in to change notification settings

tehunter/darker

Β 
Β 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Darker – reformat and lint modified Python code

master branch build status BSD 3 Clause license Latest release on PyPI Number of downloads Source code formatted using Black Change log

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.

You can help Support
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~=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

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, 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:

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] 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 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
lint = [
    "pylint",
]
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 = ["py38", "py39", "py310", "py311", "py312"]  # Overridden above
exclude = "test_*\.py"
extend_exclude = "/generated/"
force_exclude = ".*\.pyi"

[tool.isort]
profile = "black"
known_third_party = ["pytest"]
line_length = 88                  # Overridden by [tool.darker] above

Be careful to not use options which generate output which is unexpected for other tools. For example, VSCode only expects the reformat diff, so lint = [ ... ] can't be used with it.

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.

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 2.1.1: In [tool.darker], deprecate the the Black options skip_string_normalization and skip_magic_trailing_comma

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

  1. Install darker:

    $ pip install darker
    
  2. Locate your darker installation 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
    
  3. Open External tools in PyCharm/IntelliJ IDEA

    • On macOS: PyCharm -> Preferences -> Tools -> External Tools
    • On Windows / Linux / BSD: File -> Settings -> Tools -> External Tools
  4. 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 Arguments field, e.g.:

    --config /home/myself/black.cfg "$FilePath$"
    
  5. You can now format the currently opened file by selecting Tools -> External Tools -> Darker or right clicking on a file and selecting External Tools -> Darker

  6. Optionally, set up a keyboard shortcut at Preferences or Settings -> Keymap -> External Tools -> External Tools - Darker

  7. Optionally, run darker on every file save:

    1. Make sure you have the File Watcher plugin installed.
    2. Go to Preferences or Settings -> Tools -> File Watchers and 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$
    3. Uncheck "Auto-save edited files to trigger the watcher"

Visual Studio Code

  1. Install darker:

    $ pip install darker
    
  2. Locate your darker installation 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
    
  3. Make sure you have the VSCode black-formatter extension installed.

  1. Add these configuration options to VSCode (⌘ Command / Ctrl + ⇧ Shift + P and select Open 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..."]). Be sure to not enable any linters here or in pyproject.toml since VSCode won't be able to understand output from them.

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 %
  • BufWritePost to run darker once the file has been saved,
  • silent to 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:

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

  2. Create a base pre-commit configuration:

    pre-commit sample-config >.pre-commit-config.yaml
    
  3. Append to the created .pre-commit-config.yaml the following lines:

    - repo: https://github.com/akaihola/darker
      rev: v2.1.1
      hooks:
        - id: darker
  4. 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/linter tools you use to known compatible versions, for example:

- repo: https://github.com/akaihola/darker
  rev: v2.1.1
  hooks:
    - id: darker
      args:
        - --isort
        - --lint
        - mypy
        - --lint
        - flake8
        - --lint
        - pylint
      additional_dependencies:
        - black==22.12.0
        - isort==5.11.4
        - mypy==0.990
        - flake8==5.0.4
        - pylint==2.15.5

Using arguments

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: v2.1.1
  hooks:
    - id: darker
      args: [--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: Lint

on: [push, pull_request]

jobs:
  lint:
    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"
          lint: "flake8,pylint==2.13.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.

To run linters through Darker, you can provide a comma separated list of linters using the lint: option. Only flake8, pylint and mypy are supported. Other linters may or may not work with Darker, depending on their message output format. Versions can be constrained using pip syntax, e.g. "flake8>=3.9.2".

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.

Using linters

One way to use Darker is to filter linter output to only those linter messages which appeared after the modifications to source code files, as well as old messages which concern modified lines. 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:

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 with the linter command or a full command line to pass to a linter. Some examples:

  • -L flake8: enforce the Python style guide using Flake8
  • -L "mypy --strict": do static type checking using Mypy
  • --lint="pylint --ignore='setup.py'": analyze code using Pylint
  • -L cov_to_lint.py: read .coverage and list non-covered modified lines

Note: Full command lines aren't fully tested on Windows. See issue #456 for a possible bug.

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(
⚠ NOTE ⚠
Don't enable linting on the command line or in the configuration when running Darker as a reformatter in VSCode. You will confuse VSCode with unexpected output from Darker, as it only expect black's output

Syntax highlighting

Darker automatically enables syntax highlighting for the --diff, -d/--stdout and -L/--lint 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 = true option in the [tool.darker] section of pyproject.toml of your Python project's root directory,
  • the PY_COLORS=1 environment variable, and
  • the --color command line option for darker.

You can force disable syntax highlighting on terminal output using

  • the color = false option in pyproject.toml,
  • the PY_COLORS=0 environment variable, and
  • the --no-color command 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:

  1. Darker 9.0.0; Black 35.12.0 -> OK
  2. Darker 9.0.0; Black main (after 35.12.0) -> ERROR on CI test-future workflow
  3. Darker 9.0.1 released, with constraint Black<=35.12.0 -> OK
  4. Black 36.1.0 released, but Darker 9.0.1 prevents upgrade; Black 35.12.0 -> OK
  5. 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:

  1. Darker 9.0.0; Black 35.12.0 -> OK
  2. Darker 9.0.0; Black 36.1.0 -> ERROR
  3. Darker 9.0.1, constraint Black<=35.12.0; downgrades to Black 35.12.0 -> OK
  4. Darker 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.

See issue #382 and PR #430 for more information.

How does it work?

To apply Black reformatting and to modernize format strings on changed lines, Darker does the following:

  • take a git diff of Python files between REV1 and REV2 as specified using the --revision=REV1..REV2 option
  • record 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

For details on how linting support works, see Graylint documentation.

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

Contributors ✨

Thanks goes to these wonderful people (emoji key):

@wnoise
Aaron Denney

πŸ›
@agandra
Aditya Gandra

πŸ›
@kedhammar
Alfred Kedhammar

πŸ› πŸ›
@aljazerzen
AljaΕΎ Mur ErΕΎen

πŸ’»
@akaihola
Antti Kaihola

πŸ’¬ πŸ’» πŸ“– πŸ‘€ 🚧
@Ashblaze
Ashblaze

πŸ›
@levouh
August Masquelier

πŸ’» πŸ›
@AckslD
Axel Dahlberg

πŸ›
@baod-rate
Bao

πŸ’»
@qubidt
Bao

πŸ›
@falkben
Ben Falk

πŸ“– πŸ›
@brtknr
Bharat Kunwar

πŸ‘€
@bdperkin
Brandon Perkins

πŸ›
@casio
Carsten Kraus

πŸ›
@mrfroggg
Cedric

πŸ›
@chmouel
Chmouel Boudjnah

πŸ’» πŸ›
@cclauss
Christian Clauss

πŸ’»
@chrisdecker1201
Christian Decker

πŸ’» πŸ›
@KangOl
Christophe Simonis

πŸ›
@CorreyL
Correy Lim

πŸ’» πŸ“– πŸ‘€
@dkeraudren
Damien Keraudren

πŸ›
@fizbin
Daniel Martin

πŸ›
@DavidCDreher
David Dreher

πŸ›
@shangxiao
David Sanders

πŸ’» πŸ›
@dhrvjha
Dhruv Kumar Jha

πŸ› πŸ’»
@dshemetov
Dmitry Shemetov

πŸ›
@k-dominik
Dominik Kutra

πŸ› πŸ›
@virtuald
Dustin Spicuzza

πŸ›
@DylanYoung
DylanYoung

πŸ›
@phitoduck
Eric Riddoch

πŸ›
@Eyobkibret15
Eyob Kibret

πŸ›
@felixvd
Felix von Drigalski

πŸ’»
@philipgian
Filippos Giannakos

πŸ’»
@foxwhite25
Fox_white

πŸ›
@gdiscry
Georges Discry

πŸ’»
@gergelypolonkai
Gergely Polonkai

πŸ›
@muggenhor
Giel van Schijndel

πŸ’»
@jabesq
Hugo Dupras

πŸ’» πŸ›
@hugovk
Hugo van Kemenade

πŸ’»
@irynahryshanovich
Iryna

πŸ›
@yajo
Jairo Llopis

πŸ‘€
@jasleen19
Jasleen Kaur

πŸ› πŸ‘€
@jedie
Jens Diemer

πŸ›
@jenshnielsen
Jens Hedegaard Nielsen

πŸ›
@jvacek
Jonas Vacek

πŸ›
@wkentaro
Kentaro Wada

πŸ›
@Asuskf
Kevin David

πŸ›
@Krischtopp
Krischtopp

πŸ›
@leotrs
Leo Torres

πŸ›
@magnunm
Magnus N. Malmquist

πŸ›
@markddavidoff
Mark Davidoff

πŸ›
@dwt
Martin HΓ€cker

πŸ›
@matclayton
Mat Clayton

πŸ›
@Carreau
Matthias Bussonnier

πŸ’» πŸ“– πŸ‘€
@MatthijsBurgh
Matthijs van der Burgh

πŸ›
@minrk
Min RK

πŸ’»
@my-tien
My-Tien Nguyen

πŸ›
@Mystic-Mirage
Mystic-Mirage

πŸ’» πŸ“– πŸ‘€
@njhuffman
Nathan Huffman

πŸ› πŸ’»
@wasdee
Nutchanon Ninyawee

πŸ›
@Pacu2
Pacu2

πŸ’» πŸ‘€
@PatrickJordanCongenica
Patrick Jordan

πŸ›
@ivanov
Paul Ivanov

πŸ’» πŸ› πŸ‘€
@gesslerpd
Peter Gessler

πŸ›
@flying-sheep
Philipp A.

πŸ›
@RishiKumarRay
Rishi Kumar Ray

πŸ›
@ioggstream
Roberto Polli

πŸ›
@roniemartinez
Ronie Martinez

πŸ›
@rossbar
Ross Barnowski

πŸ›
@sgaist
Samuel Gaist

πŸ’»
@seweissman
Sarah

πŸ›
@sherbie
Sean Hammond

πŸ‘€
@hauntsaninja
Shantanu

πŸ›
@simgunz
Simone Gaiarin

πŸ‘€
@soxofaan
Stefaan Lippens

πŸ“–
@strzonnek
Stephan Trzonnek

πŸ›
@Svenito
Sven Steinbauer

πŸ’»
@tkolleh
TJ Kolleh

πŸ›
@talhajunaidd
Talha Juanid

πŸ’»
@guettli
Thomas GΓΌttler

πŸ›
@Timple
Tim Clephas

πŸ›
@tobiasdiez
Tobias Diez

@tapted
Trent Apted

πŸ›
@tgross35
Trevor Gross

πŸ›
@victorcui96
Victor Cui

πŸ›
@yoursvivek
Vivek Kushwaha

πŸ› πŸ“–
@Hainguyen1210
Will

πŸ›
@wjdp
Will Pimblett

πŸ› πŸ“–
@wpnbos
William Bos

πŸ›
@zachnorton4C
Zach Norton

πŸ›
@clintonsteiner
csteiner

πŸ›
@deadkex
deadkex

πŸ›
@dsmanl
dsmanl

πŸ›
@leej3
john lee

πŸ›
@jsuit
jsuit

πŸ›
@martinRenou
martinRenou

πŸ’» πŸ‘€
@mayk0gan
mayk0gan

πŸ›
@okuuva
okuuva

πŸ›
@overratedpro
overratedpro

πŸ›
@samoylovfp
samoylovfp

πŸ‘€
@simonf-dev
sfoucek

πŸ›
@rogalski
Łukasz Rogalski

πŸ’» πŸ›

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

GitHub stars trend

stargazers

About

Apply black reformatting to Python files only in regions changed since a given commit. For a practical usage example, see the blog post at https://dev.to/akaihola/improving-python-code-incrementally-3f7a

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Python 99.7%
  • Other 0.3%