Coblack is a Black-compliant formatter/rewrapper for Python comments.
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).
$ pip install coblack
(Upgrade an existing installation of Coblack by adding the --upgrade
/-U
flag).
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
.
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.
import coblack
coblack.format_file("path/to/my_file.py") # You can also pass a `pathlib.Path`.
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.
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.