python-black
[Black](https://github.com/psf/black) formatter for Sublime Text.
It is recommended to use with [LSP-pyright](https://github.com/sublimelsp/LSP-pyright).
### Installation
> There is **no need** to install `black`, but if you install it, it will not affect this package.
You can install `python-black` with package control:
1. Open your command pallete and type `Package Control: Install Package`.
2. Find this project `python-black` and press `Enter`.
#### ~~Local installation~~
~~This package has been uploaded to packagecontrol.io, so you do not need to choose local installation:~~
```shell
git clone https://github.com/thep0y/python-black.git
```
~~Copy or move the `python-black` folder to the `packages` directory of **Sublime Text 4**.~~
### Usage
#### 1 Key Binding
You can create custom key binding based on sample`Preferences - Package Settings - Python Black - Key Bindings`, such as:
```json
{
"keys": [
"ctrl+super+l"
],
"command": "black",
"args": {
"use_selection": true
}
}
```
The optional `use_selection` boolean (defaults to `true`) controls whether to format the selected region, or the entire file.
> :warning:Note: Do not **duplicate** the key binding of other packages
#### 2 Settings
There is only one modifiable property in settings:
```js
{
// Whether to automatically format the entire document when saving.
// There are three modes:
// - true (deprecated)
// - false (deprecated)
// - "on"
// - "off"
// - "smart": Automatic formatting is only enabled if there is a `black` section in the project's `pyproject.toml`
"format_on_save": "on"
}
```
This can also be toggled via `Preferences > Package Settings > Python Black > Format On Save`.
#### 3 Create Black Configuration File
You can quickly generate a black configuration file for the current project.
| Command | Description |
| ----------------------------------------------- | ------------------------------------------------------------ |
| `python-black: Create Black Configuration File` | Creates a `pyproject.toml` file in the root of the project with basic options. Opens the configuration file if it already exists. |
> :warning: If you don't want to generate a `pyproject.toml` for ***each project***, then you need to create a `black` **global configuration file**.
>
> Refer to [Black Documentation](https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#where-black-looks-for-the-file).
>If you want to disable `format_on_save` in a project that does not use `black` code style [#14](https://github.com/thep0y/python-black/issues/14), you need to add the configuration to `*.sublime-project`:
>````json
>{
> ...
> "settings": {
> ...
> "python-black": {
> "format_on_save": false
> }
> }
>}
>````
### Development
If you want to fix bugs or add features, you can read log:
- Colorful: in `python-black.log` in the `[SublimeText]/Log` directory.
- Colorless: in sublime text console.
You can also add logs where you think they should be logged as follows:
```python
from .log import child_logger
logger = child_logger(__name__)
# ...
logger.debug("...")
logger.info("...")
logger.warning("...")
logger.error("...")
# ...
```
Discussion and creation of PRs are welcome.
### TODO
- [ ] format all python files in the current project
If someone likes or gives feedback, some features may be added in the future.