Black-compliant formatter/rewrapper for Python comments.
Project description
CoBlack
CoBlack is a Black-compliant formatter/rewrapper for Python comments.
Example code
Before:
def care_for(self, favorite_plant):
self.sing_a_lullaby_to(favorite_plant) # This should help them grow. Note that this comment is too long to fit on one line, given the recommended line length.
favorite_plant.water(100 * mL) # Prevent dehydration.
After:
def care_for(self, favorite_plant):
self.sing_a_lullaby_to(favorite_plant) # This should help them grow. Note that this
# # comment is too long to fit on one line,
# # given the recommended line length.
favorite_plant.water(100 * mL) # Prevent dehydration.
The extra #
's at the beginning of each line are necessary to be Black-compliant:
If they were not there, Black would pull the comments to the start of the line,
destroying the alignment, and making the code look messier.
(Compare to how the naive way of wrapping comments looks).
Installation
$ pip install coblack
(Upgrade an existing installation of CoBlack by adding the --upgrade
/-U
flag).
Usage
In your terminal:
$ coblack my_file.py
This wraps & fills out multiline comments, and passes the result through black
.
The file is edited in-place.
Get info on additional options (such as eg -l
to set the line length)
with coblack -h
.
IDE integration
For PyCharm, create a new External Tool, as follows:
Then assign a keyboard shortcut to this tool.
This enables you to format your files quickly and often during coding sessions.
In VS Code, you'd create a new Task, in a similar fashion.
Python API
import coblack
coblack.format_file("path/to/my_file.py") # You can also pass a `pathlib.Path`.
Appendix
Naive way of wrapping comments
def care_for(self, favorite_plant):
self.sing_a_lullaby_to(favorite_plant) # This should help them grow. Note that this
# comment is too long to fit on one line, given the recommended line length.
favorite_plant.water(100 * mL) # Prevent dehydration.
Other comment styles
On own line, before code:
def care_for(self, favorite_plant):
# This should help them grow. Note that this comment is too long to fit on one line,
# given the recommended line length.
self.sing_a_lullaby_to(favorite_plant)
# Prevent dehydration.
favorite_plant.water(100 * mL)
On own line, after code:
def care_for(self, favorite_plant):
self.sing_a_lullaby_to(favorite_plant)
# This should help them grow. Note that this comment is too long to fit on one line,
# given the recommended line length.
favorite_plant.water(100 * mL)
# Prevent dehydration.
These styles don't need CoBlack; a vanilla rewrapper like any of the following will do:
- The Wrap to Column plugin for PyCharm;
- The Rewrap extension for VS Code;
- The "Wrap Paragraph at Ruler" command in Sublime Text (
Alt-Q
orAlt-⌘-Q
) ; - The
fill-paragraph
command in Emacs; or - The
gq
operator in Vim.
Project details
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.