Globality black
===============
[DISCLAIMER](./DISCLAIMER.md)
[Tech talk](https://docs.google.com/presentation/d/1Lp0jLSI5YJYOXEntxSvaHeOALAlndlgu/edit?usp=sharing&ouid=102083878154902570127&rtpof=true&sd=true)
A wrapper for [black](https://github.com/psf/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](#black-refresh).
# Table of contents
- [Globality black](#globality-black)
- [Table of contents](#table-of-contents)
- [Installation](#installation)
- [Usage](#usage)
- [CLI](#cli)
- [Pycharm](#pycharm)
- [JupyterLab](#jupyterlab)
- [VScode](#vscode)
- [Working with remotes](#working-with-remotes)
- [Shortcuts](#shortcuts)
- [Working with notebooks](#working-with-notebooks)
- [Features](#features)
- [Blank lines](#blank-lines)
- [Dotted chains](#dotted-chains)
- [Length one tuples](#length-one-tuples)
- [Comprehensions](#comprehensions)
- [Before globality-black](#before-globality-black)
- [After globality-black](#after-globality-black)
- [Partially disable globality-black](#partially-disable-globality-black)
- [Pending / Future work](#pending--future-work)
- [Black refresh](#black-refresh)
- [Magic comma](#magic-comma)
- [FAQ](#faq)
- [Tests](#tests)
- [Contributing](#contributing)
- [Submit and issue](#submit-and-issue)
- [Submit a pull request](#submit-a-pull-request)
- [Code of Conduct](#code-of-conduct)
# Installation
-----
`pip install globality-black`
# 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](https://www.jetbrains.com/help/pycharm/configuring-keyboard-and-mouse-shortcuts.html).
## JupyterLab
We can leverage [this](https://jupyterlab-code-formatter.readthedocs.io/en/latest/how-to-use.html#custom-formatter) 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:
```shell script
pip install jupyterlab_code_formatter
jupyter lab --generate-config
vim ~/.jupyter/jupyter_lab_config.py
```
You might already have some config in `jupyter_lab_config`. If so, you might want to omit
the second command above, and edit it (vim) instead.
In any case, we will add the following code:
```python
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:
```json
{
"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 last step above translates into user settings saved in
`~/.jupyter/lab/user-settings/@ryantam626/`.
- 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, install the extension
[External formatters](https://marketplace.visualstudio.com/items?itemName=SteefH.external-formatters).
Then, go to Preferences: Settings (JSON). A file `settings.json` will open. Add this to the file:
```json
"[python]": {
"editor.codeActionsOnSave": {
"source.organizeImports": true
},
"editor.defaultFormatter": "SteefH.external-formatters",
},
"isort.args":["--profile", "black"],
```
This will configure isort to run when saving, and glo-black as the default
formatter. Add also this
```json
[
"externalFormatters.languages": {
"python": {
"command": "$PATH_TO_ENV/bin/globality-black",
"arguments": [
"-",
]
}
},
"isort.interpreter": [
"$PATH_TO_ENV/bin/python"
],
]
```
setting or replacing `$PATH_TO_ENV` with whatever you need to get to the
`globality-black` Python env.
### Working with remotes
Important: these two paths have to be absolute paths, and need to be the
same everywhere you use VScode. This means that if you use VScode on remotes (e.g. an EC2 instance),
the same paths needs to exist. Obviosuly, that's not possible, since e.g.
in EC2 you'll have `/home/ubuntu/...` and in your machine `/Users/john/...`. A workaround for this is to create a symbolic link in your instance, e.g:
```bash
sudo ln -s /home/ubuntu /Users/john
```
### Shortcuts
To configure shortcuts, go to `Preferences: Keyboard Shortcuts (JSON)` from the Palette (command+shift+p). The file `keybindings.json` will open.
Add to this file:
```json
[
{
"key": "cmd+shift+j",
"command": "editor.action.formatDocument",
"when": "editorHasDocumentFormattingProvider && editorTextFocus && !editorReadonly && !inCompositeEditor"
}
]
```
This will allow you to run `globality-black` on the currently open file,
passing the content of the file via stdin.
### Working with notebooks
To format notebooks, there is a shortcut
```json
{
"key": "shift+alt+f",
"command": "notebook.formatCell",
"when": "editorHasDocumentFormattingProvider && editorTextFocus && inCompositeEditor && notebookEditable && !editorReadonly && activeEditor == 'workbench.editor.notebook'",
}
```
that you can modify if you don't like this combination. This will format the
current cell with the default formatter. I did not find a way to run isort
though. There is a "format notebook on save" option, but it's not exactly what
we configured for python files. That would run isort + glo-black.
# 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.
## Dotted chains
In a similar fashion to the "blank lines" feature, "dotted chains" allows to keep the block:
```python
return (
df_field[COLUMNS_PER_FIELD[name]]
.dropna(subset=["column"])
.reset_index(drop=True)
.assign(mapped_type=MAP_DICT[name])
)
LABELS = set(
df[df.labels.apply(len) > 0]
.flag.apply(curate)
.apply(normalize)
.unique()
)
```
the same. In this feature, **we don't explode anything** but rather protect code assuming it was
written by this in purpose for readability.
## Length one tuples
This is a very simple and specific feature. Black (at least up to 21.9b0) has a bug so that tuples
with one element are compressed as in
```python
x = (
3,
)
```
becomes
```python
x = (3,)
```
See https://github.com/psf/black/issues/1139#issuecomment-951014094. With globality-black,
will protect these.
## 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 as a default (same as `black`), `globality-black` will write the expression above as a
one-liner.
# Pending / Future work
------------
- Explode ternary operators under some criteria
- Nested comprehensions
- Magic comma for single element subscripts, due to [this](https://github.com/psf/black/pull/2942/files#diff-31972cba2ef33b6d8853302bec17d8c60e796566d67ce57e5d233f17a0c6f5a4R17-R18)
Please give us feedback if you find any issues, and check `known_failed`
# 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](https://github.com/psf/black). It is especially useful to
review [this section](https://github.com/psf/black/blob/master/docs/the_black_code_style.md), 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](https://github.com/psf/black/blob/main/docs/the_black_code_style/current_style.md#the-magic-trailing-comma).
# FAQ
---
Here we list a number of questions and solutions raised when presenting this project to other teams:
**I like this project, but this would destroy all our git history and git blames**
Our recommendation is:
1. Create a big PR for all your repo, and do the effort of reviewing the changes just once.
1. Add a `.git-blame-ignore-revs` file to your repo, ignoring the bulk commit where
`globality-black` is applied. See
[here](https://www.moxio.com/blog/43/ignoring-bulk-change-commits-with-git-blame)
for more details.
**I like most of the changes, but in some places I really prefer the way I write the code**
No problem, for those specific cases where you like more your style, just wrap the block with
`fmt:off` and `fmt:on`, see the
[Partially disable Globality Black](#partially-disable-globality-black) section.
**100 characters per line is too short / too long for me**
Just add a `pyproject.toml` to the root of your repo (as the one in this very own
project) and specify your preferred length, see the [Black refresh](#black-refresh) section.
**I want to know what will be changed before applying the changes**
Please use the `--diff` option from the CLI, see the [CLI](#cli) section.
**I want to explode list of arguments, but `globality-black` is compressing them into one line**
Please use the magic comma feature, see [Magic comma](#magic-comma).
# Tests
Run the tests as in
```
bash entrypoint.sh test
```
or simply
```
pytest .
```
Some options:
* `-s` to show prints and be able to debug
* `--pdb` to trigger debugger when having an exception
* `pytest route_to_test` to test a specific test file
* `pytest route_to_test::test_function` to test a specific test function
* `pytest route_to_test::test_function[test_case]`
* ` --cov-report term` to show coverage
You might find other code inspectors in `entrypoint.sh`. Note that these are run
against your code if opening a pull request.
# Contributing
All contributions, bug reports, security issues, bug fixes, documentation improvements, enhancements, and ideas are welcome. This section is adapted and simplified
from [pandas contribution guide](https://pandas.pydata.org/docs/development/contributing.html).
## Submit and issue
Bug reports, security issues, and enhancement requests are an important part of making open-source software more stable and are curated through Github issues. When reporting and issue or request, please fill out the issue form fully to ensure others and the core development team can fully understand the scope of the issue.
The issue will then show up to the community and be open to comments/ideas from others.
## Submit a pull request
`deboiler` is hosted on GitHub, and to contribute, you will need to sign up for a free GitHub account. We use Git for version control to allow many people to work together on the project. If you are new to Git, you can reference some of the resources in the pandas contribution guide cited above.
Also, the project follows a standard forking workflow whereby contributors fork the repository, make changes, create a feature branch, push changes, and then create a pull request. To avoid redundancy, please follow all the instructions in the pandas contribution guide cited above.
## Code of Conduct
As contributors and maintainers to this project, you are expected to abide by the code of conduct. More information can be found at the [Contributor Code of Conduct]((https://github.com/globality-corp/deboiler/.github/blob/master/CODE_OF_CONDUCT.md)).
===============
Globality black
===============
v0.1.0
--------
* TODO
Raw data
{
"_id": null,
"home_page": "https://github.com/globality-corp/globality-black",
"name": "globality-black",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "globality_black,black,python,formatter",
"author": "Globality AI",
"author_email": "ai@globality.com",
"download_url": "",
"platform": null,
"description": "Globality black\n===============\n\n[DISCLAIMER](./DISCLAIMER.md)\n\n[Tech talk](https://docs.google.com/presentation/d/1Lp0jLSI5YJYOXEntxSvaHeOALAlndlgu/edit?usp=sharing&ouid=102083878154902570127&rtpof=true&sd=true)\n\nA wrapper for [black](https://github.com/psf/black), adding pre- and post-processing\nto better align with Globality conventions.\n\n`globality-black` performs the following steps:\n\n - pre-processing: to protect from black actions\n - black\n - postprocessing: to revert / correct black actions\n\nNote: if you are not familiar with black (or need a refresh), please\nread our [Black refresh](#black-refresh).\n\n\n# Table of contents\n- [Globality black](#globality-black)\n- [Table of contents](#table-of-contents)\n- [Installation](#installation)\n- [Usage](#usage)\n - [CLI](#cli)\n - [Pycharm](#pycharm)\n - [JupyterLab](#jupyterlab)\n - [VScode](#vscode)\n - [Working with remotes](#working-with-remotes)\n - [Shortcuts](#shortcuts)\n - [Working with notebooks](#working-with-notebooks)\n- [Features](#features)\n - [Blank lines](#blank-lines)\n - [Dotted chains](#dotted-chains)\n - [Length one tuples](#length-one-tuples)\n - [Comprehensions](#comprehensions)\n - [Before globality-black](#before-globality-black)\n - [After globality-black](#after-globality-black)\n - [Partially disable globality-black](#partially-disable-globality-black)\n- [Pending / Future work](#pending--future-work)\n- [Black refresh](#black-refresh)\n - [Magic comma](#magic-comma)\n- [FAQ](#faq)\n- [Tests](#tests)\n- [Contributing](#contributing)\n - [Submit and issue](#submit-and-issue)\n - [Submit a pull request](#submit-a-pull-request)\n - [Code of Conduct](#code-of-conduct)\n\n\n# Installation\n-----\n\n`pip install globality-black`\n\n# Usage\n-----\n\nThere are two ways to use `globality-black`, via CLI, or importing the helpers in the library.\nNext, we show some typical use cases:\n\n## CLI\n\nPlease see command line arguments running `globality-black --help`.\n\n## Pycharm\n\nTo use `globality-black` in PyCharm, go to PyCharm -> Preferences... -> Tools -> External Tools -> Click + symbol\nto add new external tool.\n\n\nRecommended configuration to format the current file:\n* Program: path to `globality-black`, e.g. `/Users/marty-mcfly/miniconda3/envs/gb/bin/globality-black`\n* Arguments: `$FilePath$`\n* Working directory: `$ProjectFileDir$`\n\nRecommended configuration to check the whole repo (but not formatting it it):\n* Program: path to `globality-black`, e.g. `/Users/marty-mcfly/miniconda3/envs/gb/bin/globality-black`\n* Arguments: `. --check`\n* Working directory: `$ProjectFileDir$`\n\nNext, configure a keymap, as in [here](https://www.jetbrains.com/help/pycharm/configuring-keyboard-and-mouse-shortcuts.html).\n\n\n\n## JupyterLab\n\nWe can leverage [this](https://jupyterlab-code-formatter.readthedocs.io/en/latest/how-to-use.html#custom-formatter) extension,\nwith a custom formatter. Here we explain how to get the following options:\n\n\n\n\nThere are two ways to apply `globality-black`, see left-hand-side, or by clicking on the button next to \"Code\". We will configure\nthe extension to make it apply the `isort + globality-black` pipeline when clicking such button.\n\nTo do so, install the extension, generate the config for jupyter lab and edit it:\n\n```shell script\npip install jupyterlab_code_formatter\njupyter lab --generate-config\nvim ~/.jupyter/jupyter_lab_config.py\n```\n\nYou might already have some config in `jupyter_lab_config`. If so, you might want to omit\n the second command above, and edit it (vim) instead.\n\nIn any case, we will add the following code:\n\n```python\nfrom jupyterlab_code_formatter.formatters import SERVER_FORMATTERS\nfrom globality_black.jupyter_formatter import GlobalityBlackFormatter\nSERVER_FORMATTERS['globality-black'] = GlobalityBlackFormatter(line_length=100)\n```\n\nThen, go to the extension preferences, and add:\n\n```json\n{\n \"preferences\": {\n \"default_formatter\": {\n \"python\": [\n \"isort\",\n \"globality-black\",\n ],\n }\n },\n \"isort\": {\n \"combine_as_imports\": true,\n \"force_grid_wrap\": 4,\n \"force_to_top\": \"true\",\n \"include_trailing_comma\": true,\n \"known_third_party\": [\"wandb\", \"tqdm\"],\n \"line_length\": 100,\n \"lines_after_imports\": 2,\n \"multi_line_output\": 3,\n }\n}\n```\n\nNotes:\n - The last step above translates into user settings saved in\n`~/.jupyter/lab/user-settings/@ryantam626/`.\n - The extension is applied to all cells in the notebook. It can be configured to be applied just to\n the current cell, if interested.\n - The extension is applied to each cell in isolation. Hence, if multiple imports appear in different\n cells, they won't be merged together on top of the notebook.\n\n\n## VScode\n\nTo use `globality-black` in VScode, install the extension\n[External formatters](https://marketplace.visualstudio.com/items?itemName=SteefH.external-formatters).\n\nThen, go to Preferences: Settings (JSON). A file `settings.json` will open. Add this to the file:\n```json\n\"[python]\": {\n \"editor.codeActionsOnSave\": {\n \"source.organizeImports\": true\n },\n \"editor.defaultFormatter\": \"SteefH.external-formatters\",\n },\n \"isort.args\":[\"--profile\", \"black\"],\n```\nThis will configure isort to run when saving, and glo-black as the default\nformatter. Add also this\n```json\n[\n \"externalFormatters.languages\": {\n \"python\": {\n \"command\": \"$PATH_TO_ENV/bin/globality-black\",\n \"arguments\": [\n \"-\",\n ]\n }\n },\n \"isort.interpreter\": [\n \"$PATH_TO_ENV/bin/python\"\n ],\n]\n```\nsetting or replacing `$PATH_TO_ENV` with whatever you need to get to the\n`globality-black` Python env.\n\n### Working with remotes\nImportant: these two paths have to be absolute paths, and need to be the\nsame everywhere you use VScode. This means that if you use VScode on remotes (e.g. an EC2 instance),\nthe same paths needs to exist. Obviosuly, that's not possible, since e.g.\nin EC2 you'll have `/home/ubuntu/...` and in your machine `/Users/john/...`. A workaround for this is to create a symbolic link in your instance, e.g:\n```bash\nsudo ln -s /home/ubuntu /Users/john\n```\n\n### Shortcuts\n\n To configure shortcuts, go to `Preferences: Keyboard Shortcuts (JSON)` from the Palette (command+shift+p). The file `keybindings.json` will open.\n Add to this file:\n```json\n[\n {\n \"key\": \"cmd+shift+j\",\n \"command\": \"editor.action.formatDocument\",\n \"when\": \"editorHasDocumentFormattingProvider && editorTextFocus && !editorReadonly && !inCompositeEditor\"\n }\n]\n```\nThis will allow you to run `globality-black` on the currently open file,\npassing the content of the file via stdin.\n\n### Working with notebooks\n\nTo format notebooks, there is a shortcut\n```json\n{\n \"key\": \"shift+alt+f\",\n \"command\": \"notebook.formatCell\",\n \"when\": \"editorHasDocumentFormattingProvider && editorTextFocus && inCompositeEditor && notebookEditable && !editorReadonly && activeEditor == 'workbench.editor.notebook'\",\n}\n```\nthat you can modify if you don't like this combination. This will format the\ncurrent cell with the default formatter. I did not find a way to run isort\nthough. There is a \"format notebook on save\" option, but it's not exactly what\n we configured for python files. That would run isort + glo-black.\n\n\n# Features\n--------\n\n## Blank lines\n\nBlack would remove those blank lines after `wandb` and `scikit-learn` below:\n\n```\ngraph.use(\n \"wandb\",\n\n \"scikit-learn\",\n\n # we love pandas\n \"pandas\",\n)\n```\n\n`globality-black` protects those assuming the developer added them for readability.\n\n\n## Dotted chains\n\nIn a similar fashion to the \"blank lines\" feature, \"dotted chains\" allows to keep the block:\n\n```python\nreturn (\n df_field[COLUMNS_PER_FIELD[name]]\n .dropna(subset=[\"column\"])\n .reset_index(drop=True)\n .assign(mapped_type=MAP_DICT[name])\n)\n\nLABELS = set(\n df[df.labels.apply(len) > 0]\n .flag.apply(curate)\n .apply(normalize)\n .unique()\n)\n```\n\nthe same. In this feature, **we don't explode anything** but rather protect code assuming it was\nwritten by this in purpose for readability.\n\n## Length one tuples\n\nThis is a very simple and specific feature. Black (at least up to 21.9b0) has a bug so that tuples\nwith one element are compressed as in\n\n```python\nx = (\n 3,\n)\n```\nbecomes\n```python\nx = (3,)\n```\nSee https://github.com/psf/black/issues/1139#issuecomment-951014094. With globality-black,\nwill protect these.\n\n\n## Comprehensions\n\nExplode comprehensions\n* all dict comprehensions\n* any comprehension with an if\n* any comprehension with multiple for loops (see examples below)\n* list / set comprehensions where the element:\n - has a ternary operator (see examples below)\n - has another comprehension\n\nFor everything else, we rely on `black`. Examples:\n\n### Before globality-black\n\n```\n[3 for _ in range(10)]\n\n[3 for i in range(10) if i < 4]\n\n{\"a\": 3 for _ in range(4)}\n\n{\"a\": 3 for _ in range(4) if i < 4}\n\n[\"odd\" if i %% 2 == 0 else \"even\" for _ in range(10)]\n\ndouble_comp1 = [3*i*j for i in range(10) for j in range(4)]\n\ndouble_comp2 = [[i for i in range(7) if i < 5] for j in range(10)]\n\ndouble_comp3 = {i: [i for i in range(7) if i < 5] for j in range(10) if i < 2}\n```\n\n### After globality-black\n\n```\n[3 for _ in range(10)]\n\n[\n 3\n for i in range(10)\n if i < 4\n]\n\n{\n \"a\": 3\n for _ in range(4)\n}\n\n{\n \"a\": 3\n for _ in range(4)\n if i < 4\n}\n\n[\n \"odd\" if i %% 2 == 0 else \"even\"\n for _ in range(10)\n]\n\ndouble_comp1 = [\n 3 * i * j\n for i in range(10)\n for j in range(4)\n]\n\ndouble_comp2 = [\n [i for i in range(7) if i < 5]\n for j in range(10)\n]\n\ndouble_comp3 = {\n i: [i for i in range(7) if i < 5]\n for j in range(10)\n if i < 2\n}\n```\n\nNote that in the last two comprehensions, the nested comprehensions are not exploded even though\nhaving an if. This is a limitation of `globality-black`, but we believe not very frequent\nin everyday cases. If you really want to explode those and make `globality-black` respect it,\nplease use the feature explained next.\n\n## Partially disable globality-black\n\nIf you see some block where you don't want to apply `globality-black`, wrap it\nwith `# fmt.off` and `# fmt:on` and it will be ignored. Note that this is the same syntax as\nfor `black`. For example, for readability you might want to do something as:\n\n```\n# fmt: off\nfiles_to_read = [\n (f\"{key1}_{key2}\", key1, key2, key1 + key2)\n for key1 in range(10)\n]\n# fmt: on\n```\n\nNote that as a default (same as `black`), `globality-black` will write the expression above as a\none-liner.\n\n# Pending / Future work\n------------\n\n- Explode ternary operators under some criteria\n- Nested comprehensions\n- Magic comma for single element subscripts, due to [this](https://github.com/psf/black/pull/2942/files#diff-31972cba2ef33b6d8853302bec17d8c60e796566d67ce57e5d233f17a0c6f5a4R17-R18)\n\nPlease give us feedback if you find any issues, and check `known_failed`\n\n\n# Black refresh\n--------\n\n`black` is an opinionated Python formatter that tries to save as much vertical space as possible. In\nthis regard, it compresses lines to the maximum character length that has been configured. `black`'s\ndefault is 88, whereas in `globality-black` we use a default of 100 characters, as agreed for\nGlobality repos globally. If you want to have a custom max character length, add a `pyproject.toml`\nfile to the root of your repo. This works the same way as in `black`, and `globality-black` will\ntake your config from there.\n\nSee how `black` works in their [README](https://github.com/psf/black). It is especially useful to\nreview [this section](https://github.com/psf/black/blob/master/docs/the_black_code_style.md), where\nimportant recent features are explained.\n\n## Magic comma\n\n`black` added a feature at the end of 2020 that we used to call the \"magic comma\". It's one of the\nfirst examples where `black` is giving a bit of freedom to the developer on how the final code will\nlook like (apart from `fmt:off` and `fmt:on` to ignore `black` entirely). Read more about it\n[here](https://github.com/psf/black/blob/main/docs/the_black_code_style/current_style.md#the-magic-trailing-comma).\n\n# FAQ\n---\n\nHere we list a number of questions and solutions raised when presenting this project to other teams:\n\n**I like this project, but this would destroy all our git history and git blames**\n\nOur recommendation is:\n 1. Create a big PR for all your repo, and do the effort of reviewing the changes just once.\n 1. Add a `.git-blame-ignore-revs` file to your repo, ignoring the bulk commit where\n `globality-black` is applied. See\n [here](https://www.moxio.com/blog/43/ignoring-bulk-change-commits-with-git-blame)\n for more details.\n\n**I like most of the changes, but in some places I really prefer the way I write the code**\n\nNo problem, for those specific cases where you like more your style, just wrap the block with\n`fmt:off` and `fmt:on`, see the\n[Partially disable Globality Black](#partially-disable-globality-black) section.\n\n**100 characters per line is too short / too long for me**\n\nJust add a `pyproject.toml` to the root of your repo (as the one in this very own\nproject) and specify your preferred length, see the [Black refresh](#black-refresh) section.\n\n**I want to know what will be changed before applying the changes**\n\nPlease use the `--diff` option from the CLI, see the [CLI](#cli) section.\n\n**I want to explode list of arguments, but `globality-black` is compressing them into one line**\n\nPlease use the magic comma feature, see [Magic comma](#magic-comma).\n\n# Tests\n\nRun the tests as in\n\n```\nbash entrypoint.sh test\n```\nor simply\n```\npytest .\n```\n\nSome options:\n* `-s` to show prints and be able to debug\n* `--pdb` to trigger debugger when having an exception\n* `pytest route_to_test` to test a specific test file\n* `pytest route_to_test::test_function` to test a specific test function\n* `pytest route_to_test::test_function[test_case]`\n* ` --cov-report term` to show coverage\n\nYou might find other code inspectors in `entrypoint.sh`. Note that these are run\nagainst your code if opening a pull request.\n\n# Contributing\n\nAll contributions, bug reports, security issues, bug fixes, documentation improvements, enhancements, and ideas are welcome. This section is adapted and simplified\nfrom [pandas contribution guide](https://pandas.pydata.org/docs/development/contributing.html).\n\n## Submit and issue\n\nBug reports, security issues, and enhancement requests are an important part of making open-source software more stable and are curated through Github issues. When reporting and issue or request, please fill out the issue form fully to ensure others and the core development team can fully understand the scope of the issue.\n\nThe issue will then show up to the community and be open to comments/ideas from others.\n\n## Submit a pull request\n\n`deboiler` is hosted on GitHub, and to contribute, you will need to sign up for a free GitHub account. We use Git for version control to allow many people to work together on the project. If you are new to Git, you can reference some of the resources in the pandas contribution guide cited above.\n\nAlso, the project follows a standard forking workflow whereby contributors fork the repository, make changes, create a feature branch, push changes, and then create a pull request. To avoid redundancy, please follow all the instructions in the pandas contribution guide cited above.\n\n## Code of Conduct\n\nAs contributors and maintainers to this project, you are expected to abide by the code of conduct. More information can be found at the [Contributor Code of Conduct]((https://github.com/globality-corp/deboiler/.github/blob/master/CODE_OF_CONDUCT.md)).\n\n\n===============\nGlobality black\n===============\n\n\nv0.1.0\n--------\n\n* TODO\n",
"bugtrack_url": null,
"license": "",
"summary": "A wrapper for black adding new features",
"version": "2023.46.126",
"project_urls": {
"Homepage": "https://github.com/globality-corp/globality-black"
},
"split_keywords": [
"globality_black",
"black",
"python",
"formatter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7d22adc717ca7ded3c71695b0386d7b0ae802b0c98f35b8033fa325f3098e6bd",
"md5": "e50018fd33de81a9c9326e517ea90a83",
"sha256": "97885471c2ab8074c588db18ce8ffedc0aab21c298f6df53fcbb979210c313b1"
},
"downloads": -1,
"filename": "globality_black-2023.46.126-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e50018fd33de81a9c9326e517ea90a83",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 21044,
"upload_time": "2023-11-17T22:59:08",
"upload_time_iso_8601": "2023-11-17T22:59:08.269915Z",
"url": "https://files.pythonhosted.org/packages/7d/22/adc717ca7ded3c71695b0386d7b0ae802b0c98f35b8033fa325f3098e6bd/globality_black-2023.46.126-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-17 22:59:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "globality-corp",
"github_project": "globality-black",
"github_not_found": true,
"lcname": "globality-black"
}
JSON
