DEV Community

Sahdev Garg
Sahdev Garg

Posted on • Updated on

Python code formatter Black

Writing well-formatted code is very important, breaking the actual programs in easy to understand small programs as compared to having a more complex program helps in better understanding of code and helps in maintaining code quality. In python we have an automated package Black which helps in ensures code quality.

Image black

What is Black?

Black is known as the uncompromised Python code formatter. Unlike flake8 or pycodestyle rather then telling where the issue is and ask you to manually fix it Black not only report format errors but also fixes them. Black does not have a lot of options to tinker with and has a lot of opinion on how your code should look and feel.
Black isn't for everyone and you may find something that is a dealbreaker for you personally, which is okay! The current Black code style is described here.
Black can be easily integrated with many editors such as Vim, Emacs, VSCode, Atom or a version control system like GIT.

Installation

Black requires Python 3.6.2+ to run but has a capability to format Python 2 code too.
For Python 3.6.2+ using pip.

pip install black

Python 2 support needs the typed_ast dependency, which will be installed with pip install black[python2]. If you want to format Jupyter Notebooks, install pip install black[jupyter].
If you can't wait for the latest hotness and want to install from GitHub, use:

pip install git+git://github.com/psf/black

Usage of Black

In simplest if we just want to format a file or a folder of files simple run the following command in terminal.
$ black {source_file_or_directory}...
You can run Black as a package if running it as a script doesn't work:
$ python -m black {source_file_or_directory}...
You can also pass code as a string using the -c / --code option.
$ black --code "print ( 'hello, black world' )"
print("hello, black world")

you can pass -v / --verbose that will cause Black to also emit messages about files that were not changed or were ignored due to exclusion patterns.

$ black -v spell_checker/
spell_checker/pycache ignored: matches the .gitignore file content
spell_checker/init.py wasn't modified on disk since last run.
spell_checker/spell_checker_util.py wasn't modified on disk since last run.
spell_checker/spelling_checker.py wasn't modified on disk since last run.
All done! ✨ 🍰 ✨
3 files left unchanged.

Black Magic in action

Let's create an unformatted file name "black_test.py" and we want to format it using black. Below is the code snippet from the file before formatting.

def find_no_in_list(
s,
no
):
s = list(s
)
for i in range(len(s) - 1):
if s[i] == no:
return i
else:
return -1
if name == "main":
print(
find_no_in_list([1,
2,
3,
4],
3)
)

After running the following command in terminal

$ black black_test.py
Output file:
def find_no_in_list(s, no):
s = list(s)
for i in range(len(s) - 1):
if s[i] == no:
return i
else:
return -1
if name == "main":
print(find_no_in_list([1, 2, 3, 4], 3))

Conclusion

It's always a good practise to write a well formatted code so that it will easier to understand and manage in future so Black is must to have in your IDE when working with python so that you have a well formatted code everytime automatically.
Next read understand pep8

Discussion (1)

Collapse
remcoboerma profile image
Remco Boerma

Pycharm + black plugin + host blackd locally (on startup or login) and you get automagically black formatting on every file save in pycharm.
Blacksolutely fantastic.