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

This will get you the

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

(👆 back to top of ReadMe).

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 or Alt-⌘-Q) ;
• The fill-paragraph command in Emacs; or
• The gq operator in Vim.