A wrapper for black adding new features
Project description
Globality black
A wrapper for black, adding pre- and post-processing to better align with Globality conventions.
globality-black
performs the following steps:
- pre-processing: to protect from black actions.
- black
- postprocessing: to revert / correct black actions.
Note: if you are not familiar with black (or need a refresh), please read our Black refresh.
Usage
There are two ways to use globality-black
, via CLI, or importing the helpers in the library.
Next, we show some typical use cases:
CLI
Please see command line arguments running globality-black --help
.
Pycharm
To use globality-black
in PyCharm, go to PyCharm -> Preferences... -> Tools -> External Tools -> Click + symbol
to add new external tool.
Recommended configuration to format the current file:
- Program: path to
globality-black
, e.g./Users/marty-mcfly/miniconda3/envs/gb/bin/globality-black
- Arguments:
$FilePath$
- Working directory:
$ProjectFileDir$
Recommended configuration to check the whole repo (but not formatting it it):
- Program: path to
globality-black
, e.g./Users/marty-mcfly/miniconda3/envs/gb/bin/globality-black
- Arguments:
. --check
- Working directory:
$ProjectFileDir$
Next, configure a keymap, as in here.
Jupyterlab
We can leverage this extension, with a custom formatter. Here we explain how to get the following options:
There are two ways to apply globality-black
, see left-hand-side, or by clicking on the button next to "Code". We will configure
the extension to make it apply the isort + globality-black
pipeline when clicking such button.
To do so, install the extension, generate the config for jupyter lab and edit it:
pip install jupyterlab_code_formatter
jupyter notebook --generate-config
vim ~/.jupyter/jupyter_notebook_config.py
with the following code:
from jupyterlab_code_formatter.formatters import SERVER_FORMATTERS
from globality_black.jupyter_formatter import GlobalityBlackFormatter
SERVER_FORMATTERS['globality-black'] = GlobalityBlackFormatter(line_length=100)
Then, go to the extension preferences, and add:
{
"preferences": {
"default_formatter": {
"python": [
"isort",
"globality-black",
],
}
},
"isort": {
"combine_as_imports": true,
"force_grid_wrap": 4,
"force_to_top": "true",
"include_trailing_comma": true,
"known_third_party": ["wandb", "tqdm"],
"line_length": 100,
"lines_after_imports": 2,
"multi_line_output": 3,
}
}
Notes:
- The extension is applied to all cells in the notebook. It can be configured to be applied just to the current cell, if interested.
- The extension is applied to each cell in isolation. Hence, if multiple imports appear in different cells, they won't be merged together on top of the notebook.
VScode
To use globality-black
in VScode go to Preferences: Keyboard Shortcuts (JSON) from the Palette (command+shift+p)
It will open a file named keybindings.json
, then add to this file :
[
{
"key": "the shortcut you want (ctrl+b for example)",
"command": "workbench.action.terminal.sendSequence",
"args": {
"text": "globality-black ${file}"
}
}
]
This will allow you to run globality-black
per file.
To run globality-black
to the folder opened in VSCode just replace file by workspaceFolder.
You can also add any arguments supported by the CLI (--check or --diff are recommended to avoid formatting the whole repo)
Features
Blank lines
Black would remove those blank lines after wandb
and scikit-learn
below:
graph.use(
"wandb",
"scikit-learn",
# we love pandas
"pandas",
)
globality-black
protects those assuming the developer added them for readability.
Comprehensions
Explode comprehensions
- all dict comprehensions
- any comprehension with an if
- any comprehension with multiple for loops (see examples below)
- list / set comprehensions where the element:
- has a ternary operator (see examples below)
- has another comprehension
For everything else, we rely on black
. Examples:
Before globality-black
[3 for _ in range(10)]
[3 for i in range(10) if i < 4]
{"a": 3 for _ in range(4)}
{"a": 3 for _ in range(4) if i < 4}
["odd" if i %% 2 == 0 else "even" for _ in range(10)]
double_comp1 = [3*i*j for i in range(10) for j in range(4)]
double_comp2 = [[i for i in range(7) if i < 5] for j in range(10)]
double_comp3 = {i: [i for i in range(7) if i < 5] for j in range(10) if i < 2}
After globality-black
[3 for _ in range(10)]
[
3
for i in range(10)
if i < 4
]
{
"a": 3
for _ in range(4)
}
{
"a": 3
for _ in range(4)
if i < 4
}
[
"odd" if i %% 2 == 0 else "even"
for _ in range(10)
]
double_comp1 = [
3 * i * j
for i in range(10)
for j in range(4)
]
double_comp2 = [
[i for i in range(7) if i < 5]
for j in range(10)
]
double_comp3 = {
i: [i for i in range(7) if i < 5]
for j in range(10)
if i < 2
}
Note that in the last two comprehensions, the nested comprehensions are not exploded even though
having an if. This is a limitation of globality-black
, but we believe not very frequent
in everyday cases. If you really want to explode those and make globality-black
respect it,
please use the feature explained next.
Partially disable globality-black
If you see some block where you don't want to apply globality-black
, wrap it
with # fmt.off
and # fmt:on
and it will be ignored. Note that this is the same syntax as
for black
. For example, for readability you might want to do something as:
# fmt: off
files_to_read = [
(f"{key1}_{key2}", key1, key2, key1 + key2)
for key1 in range(10)
]
# fmt: on
Note that by as a default (same as black
), globality-black
will write the expression above as a
one-liner.
Pending / Future work
- Usage in VScode
Please give us feedback if you find any issues
Black refresh
black
is an opinionated Python formatter that tries to save as much vertical space as possible. In
this regard, it compresses lines to the maximum character length that has been configured. black
's
default is 88, whereas in globality-black
we use a default of 100 characters, as agreed for
Globality repos globally. If you want to have a custom max character length, add a pyproject.toml
file to the root of your repo. This works the same way as in black
, and globality-black
will
take your config from there.
See how black
works in their README. It is especially useful to
review this section, where
important recent features are explained.
Magic comma
black
added a feature at the end of 2020 that we used to call the "magic comma". It's one of the
first examples where black
is giving a bit of freedom to the developer on how the final code will
look like (apart from fmt:off
and fmt:on
to ignore black
entirely). Read more about it
here.
=============== Globality black
v0.1.0
- TODO
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for globality-black-2021.26.609.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 057e165953172ca926b12e33c46ca791ffab2acc7d967cd0ffffd21e48252b6d |
|
MD5 | 57fd3092cbab61b33913261dba10205b |
|
BLAKE2b-256 | 9cf04ecf6c37cf15c4ba2d1632b135e2740af099c372484de5a7926553d1462a |