Black is an uncompromising opinionated formatter for Python. The formatter is widely used in the industry and unlike many formatters, especially those in the JavaScript world, it doesn't have very many overrides available. One of the main overrides you may want to take into consideration is the max line length of the code. Black has the maximum allowed characters in a line set to 88, which in my opinion is too little, but you may disagree.
You can overwrite the line length by using the --line-length or -l flag and pass the new maximum number of characters you would like. I would recommend something around 100, but obviously use something you or your team prefer.
Read the Black Documentation for more information: Black documentation
Installing Black
Install black for your project with:
pip install black
Now in your terminal, at the root of your project, you can run the black command to check what files in your code will be re-formatted:
black . --diff
I recommend running with the --diff flag first to double-check the files that will be affected by the command. Black tries to ignore files present in your .gitignore file, but it could take some time if Black tries to format code in your virtual environment or any other area you don't want formatting. If you find that Black is formatting files you don't want it to format, you can either update your .gitignore file or you could pass an option to the command to be more specific.
If you would like to only format files in specific directories, you can run the following command:
black src\**\*.py
This command tells Black which files we want it to parse. The above command formats:
Only files in the
srcdirectoryWithin that directory, any directory, denoted by
**Within those directories, only files ending with the
*pyextension
Automating in PyCharm
Navigate to your external tool settings in PyCharm:
On macOS:
PyCharm -> Preferences -> Tools -> External Tools
On Windows / Linux:
File -> Settings -> Tools -> External Tools
Click the + icon to add a new external tool and fill out the required sections:
The name and description don't really matter but should be something you can easily identify.
The program section should point to the executable you installed with pip earlier. This may be in your local installation folder but will be in your virtual environment if you are using one. If you are not using a virtual environment, you can find the location of black with the following command:
On macOS / Linux / BSD:
$ which black
/usr/local/bin/black # possible location
On Windows:
$ where black
%LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe # possible location
The arguments section indicates the arguments you would pass to Black if running the command manually. In this instance, I have passed the string indicating which files I want to process and a maximum line length with the -l flag to indicate that I would like to override Black's default value of 88.
⌨ Add a keyboard shortcut for Black
📜 Note that this step is not required if you don't want to be able to execute black over the entire project with a keyboard shortcut.
You can add a keyboard shortcut for Black within your preferences/settings by going to Keymap and selecting External Tools -> External Tools in the folder view to the right. You should see your black external tool we just created. In my instance, the external tool is not presented with a nice name but is just called External Tool. Right-click this and select Add keyboard shortcut:
In the box above type the keyboard shortcut you prefer, making sure not to override other keyboard shortcuts you may use. I used Ctrl+Shift+B but use whatever you like.
Now when you use your keyboard shortcut in the code editor, you should get a command output detailing what files have been formatted by Black.
💾 Reformatting when saving a file
If you would like to reformat your code when you save the file, you can configure that in the preferences/settings too. Within the Tools -> Black section:
Select the instance of Python you would like to use, in my instance, I have selected Python from my virtual environment and then add any commands you would like present within the Settings section. I have not provided a path to any files being formatted as this is only formatting the file being saved, but I have still opted to override the maximum line length with the -l flag.
Now when you save a file, you should have it automatically formatted using Black!