Let's meet Black: Python Code Formatting
Tags: python, tools
Published: 2024-02-07 11:00:00

While each developer may have different preferences for coding style, the importance of a unified style is very important for maintaining readable code.
This has a bigger importance if you think of a project in which many developers are involved.

In Python exists the 'Style Guide for Python Code' known as [PEP 8](https://peps.python.org/pep-0008/), which recommends specific code conventions to maintain a standardized code format.
This style guide is about:

- indentation
- imports
- max line length
- name conventions
- comments
- etc

In the realm of Python development, there is a multitude of code formatters that adhere to PEP 8 guidelines. Today, we will briefly discuss how to install and utilize [black](https://black.readthedocs.io/en/stable/).

## Basics

Let's stop talking and get our hands dirty because it's a great way to learn.

First of all, let's install it using pip:

```bash
$ pip install black
```
Once installed, to use it, just execute the following command:

```bash
$ black {source_file_or_directory}
```
This command will initiate black with the standard configuration and reformat all the Python files it finds.

### Options

As you can see running Black is quite simple but what if we want not to change the file/s but perform only a check ?
We can use the options furnished by Black.

#### --check
Do not change the file but return only the exit value:

- 0, nothing to change
- 1, some files would be reformatted
- 123, an internal error occurred.

**Example**
```bash
black --check main.py 
would reformat main.py

Oh no! 💥 💔 💥
1 file would be reformatted.

```

#### --diff

Even this command does not reformat the files but prints the diff which indicates the changes.
[Note]: use --color if you want colored diff.

I suggest reading the [documentation](https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html) for a complete list of options.
In my opinion some of the most useful are:
- *--required-version*
- *--exclude*.

**Example**

```diff
black --diff --color main.py 
--- main.py	2023-09-08 21:03:49.860827+00:00
+++ main.py	2024-02-04 22:31:31.130282+00:00
@@ -5,29 +5,31 @@
 from starlette.middleware.base import BaseHTTPMiddleware
 
 from app.frontend import pages
-from app.core import config 
+from app.core import config

-app.include_router(pages.router, prefix='')
+app.include_router(pages.router, prefix="")
-
-
-
-
-
would reformat main.py

All done! ✨ 🍰 ✨
1 file would be reformatted.
```

## Configuration
If you want to customize the configuration of Black you can remember the list of the options or configure it using a configuration file.

Black uses by default the [*pyproject.toml*](https://github.com/toml-lang/toml) file.
This file contains a section for each different tool we want to use. The use of a configuration file like pyproject.toml is quite a good choice and helps the contributors to use the same tools and configurations you're using.

Black uses *[tool.black]* section, the option names/keys are the same as the long names of options used in the command line. Below you can see an example:

```toml
[tool.black]
line-length = 80
target-version = ['py37']
```
## Conclusion
We've explored, briefly, the formatted called __Black__ talking about the aim of this tool, how to use and how to configure it using a configuration file.
I hope this post can help you to improve your repository and code.