README.md

python-black

Black formatter for Sublime Text.

It is recommended to use it with LSP-pyright.

Installation

There is no need to install black. However, if you choose to 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:

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 samplePreferences - Package Settings - Python Black - Key Bindings, such as:

{
  "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.

⚠️Note: Do not duplicate the key binding of other packages.

2 Settings

There are some modifiable properties in settings:

{
   // Whether to automatically format the entire document when saving.
   // There are three modes:
   //    - "on"
   //    - "off"
   //    - "smart": Automatic formatting is only enabled if there is a `black` section in the project's `pyproject.toml`
   "format_on_save": "on",
   // Black [OPTIONS]
   // The priority of loading options for Black is:
   // Sublime project settings > Configuration file > Sublime package user settings > Sublime package default settings
   "options": {
      // Python versions that should be supported by Black's output.
      "target_version": [],
      // How many characters per line to allow.
      "line_length": 88,
      // Format all input files like typing stubs regardless of file extension (useful when piping source on standard input).
      "is_pyi": false,
      // Skip the first line of the source code.
      "skip_source_first_line": false,
      // Don't normalize string quotes or prefixes.
      "skip_string_normalization": false,
      // Don't use trailing commas as a reason to split lines.
      "skip_magic_trailing_comma": false
   }
}

The format_on_save can also be toggled via Preferences > Package Settings > Python Black > Format On Save.

The Black options can also be configured in sublime-project:

{
  "settings": {
    // ...
    "python-black": {
      "options": {
        "line_length": 127,
        "skip_string_normalization": true
      }
    }
  }
}

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.

⚠️ If you don't want to generate a pyproject.toml for each project, you need to create a global configuration file for Black.

Refer to Black Documentation.

If you want to disable format_on_save in a project that does not use black code style #14, you need to add the configuration to *.sublime-project:

{
	...
	"settings": {
		...
		"python-black": {
			"format_on_save": "off"
		}
	}
}

Development

If you want to fix bugs or add features, you can read the logs:

• Colorful: in python-black.log in the [SublimeText]/Log directory.

• Colorless: in the Sublime Text console.

You can also add logs where you think they should be logged as follows:

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