Black for code formatting

Black github
Black github
2019-02-07
Python


black_logo

Table of Contents

1. What is black

Black is a python code formatter that allows developers to focus on code itself. You can try it online here.

From their github:

Black is the uncompromising Python code formatter. By using it, you agree to cede control over minutiae of hand-formatting. In return, Black gives you speed, determinism, and freedom from pycodestyle nagging about formatting. You will save time and mental energy for more important matters.

The best way to explain it will using and example.

1.1. Input

from seven_dwwarfs import Grumpy, Happy, Sleepy, Bashful, Sneezy, Dopey, Doc
x = {  'a':37,'b':42,

'c':927}

x = 123456789.1234

if very_long_variable_name is not None and \
 very_long_variable_name.field > 0 or \
 very_long_variable_name.is_debug:
 z = 'hello '+'world'
else:
 world = 'world'
 a = 'hello {}'.format(world)
 f = rf'hello {world}'
if (this
and that): y = 'hello ''world'#FIXME: https://github.com/ambv/black/issues/26
class Foo  (     object  ):
  def f    (self   ):
    return       37*-2
  def g(self, x,y=42):
      return y
def f  (   a: List[ int ]) :
  return      37-a[42-u :  y**3]
def very_important_function(template: str,*variables,file: os.PathLike,debug:bool=False,):
    """Applies `variables` to the `template` and writes to `file`."""
    with open(file, "w") as f:
     x = f.read()
regular_formatting = [
    0,  1,  2,
    3,  4,  5,
    6,  7,  8,
]

1.2. Output from black

from seven_dwwarfs import (
    Grumpy,
    Happy,
    Sleepy,
    Bashful,
    Sneezy,
    Dopey,
    Doc,
)

x = {"a": 37, "b": 42, "c": 927}

x = 123_456_789.1234

if (
    very_long_variable_name is not None
    and very_long_variable_name.field > 0
    or very_long_variable_name.is_debug
):
    z = "hello " + "world"
else:
    world = "world"
    a = "hello {}".format(world)
    f = rf"hello {world}"
if this and that:
    y = (
        "hello " "world"
    )  # FIXME: https://github.com/ambv/black/issues/26


class Foo(object):
    def f(self):
        return 37 * -2

    def g(self, x, y=42):
        return y


def f(a: List[int]):
    return 37 - a[42 - u : y ** 3]


def very_important_function(
    template: str,
    *variables,
    file: os.PathLike,
    debug: bool = False,
):
    """Applies `variables` to the `template` and writes to `file`."""
    with open(file, "w") as f:
        x = f.read()


regular_formatting = [0, 1, 2, 3, 4, 5, 6, 7, 8]

2. Installation and usage of black

You can install black using pip with:

pip install black

You can 'black' any python file or directory with:

# Run on a file
black file.py

# Run on a folder
black src/

You can use a pyproject.toml file to configure some things in black. For example I like having a 100 line-length, so I would use:

pyproject.toml 
[tool.black]
line-length = 100
py36 = true

3. Sublack

Sublack is a sublime extension to run black.

To install sublack you should:

  1. Open sublime
  2. Press CTRL + SHIFT + P
  3. Write Package Controll: Install Package
  4. Find sublack

After that you can use sublack by:

But the best part will be if you set sublack to auto format the current file when saving. This way every time you save a file it will be blackened. To do so you should:

  1. With sublime go to Preferences
  2. Select Package Settings
  3. Select sublack
  4. Select Settings
  5. Change black_on_save to true

Note:

If you are unable to modify the file, copy it's contents and save it in a new file in the same location (you can see the location at the top of sublime). In my case the path is C:\Users\Villoro\AppData\Roaming\Sublime Text 3\Packages\sublack\sublack.sublime-settings

I usually use sublime but there are black extensions for other programs as well.

Subscribe to the mailing list