Apply Black formatting only in regions changed since last commit
Project description
What?
This is a small utility built on top of the black Python code formatter to enable formatting of only regions which have changed since the last Git commit.
Why?
Python code should be black, just like outer space. However, sometimes people insist on staying on the Earth. Since there’s no complete blackness on the Earth, you eventually settle for just a little darker as a compromise.
In other words, you want to use black for the code you write, but for some reason you don’t want to convert the whole files, e.g. 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 a stopgap measure, and you should avoid using it if you can.
How?
To install, use:
pip install darker
The darker <myfile.py> command reads the original file, formats it using black, combines original and formatted regions based on edits, and writes back over the original file.
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.
Example:
$ mkdir test && cd test && git init
Initialized empty Git repository in /tmp/test/.git/
$ echo "if True: print('hi')\n\nif False: print('there')" | tee test.py
if True: print('hi')
if False: print('there')
$ git add test.py && git commit -m "Initial commit"
[master (root-commit) a0c7c32] Initial commit
1 file changed, 3 insertions(+)
create mode 100644 test.py
$ echo "if True: print('changed')\n\nif False: print('there')" | tee test.py
if True: print('changed')
if False: print('there')
$ darker test.py && cat test.py
if True:
print("changed")
if False: print('there')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
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
Open External tools in PyCharm/IntelliJ IDEA
On macOS:
PyCharm -> Preferences -> Tools -> External Tools
On 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$"
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
Optionally, run darker on every file save:
Make sure you have the File Watcher plugin installed.
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$
Uncheck “Auto-save edited files to trigger the watcher”
License
BSD. See LICENSE.rst.
Prior art
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file darker-0.1.1.tar.gz.
File metadata
- Download URL: darker-0.1.1.tar.gz
- Upload date:
- Size: 11.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/45.2.0 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/3.7.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | ec20142ba9d3270d8f5cbfaf78a295a02b0300baebd30318e58adffe3eb0ef0b |
|
| MD5 | 0afe3812737f0220c2736476614f8bae |
|
| BLAKE2b-256 | d3825ba1873375805bfef6d29038a26e7dd5a014e53586f549d0a74660c8c691 |
File details
Details for the file darker-0.1.1-py3-none-any.whl.
File metadata
- Download URL: darker-0.1.1-py3-none-any.whl
- Upload date:
- Size: 12.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/45.2.0 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/3.7.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | bfbdfb16aa6403fcaf1997b213d405ed723a762dd09e356cb8defec23b5ae2f7 |
|
| MD5 | ba1d57c9c9dcc29e6bce8bbe6a0ca537 |
|
| BLAKE2b-256 | 5a3b4810ee522519aee2b9af96578996b28e885f7304b8ef5fe4191fb9dd5185 |
