https://github.com/microsoft/vscode-black-formatter

Formatting support for Python using the Black formatter
https://github.com/microsoft/vscode-black-formatter

Last synced: 3 months ago
JSON representation

Formatting support for Python using the Black formatter

• Host: GitHub
• URL: https://github.com/microsoft/vscode-black-formatter
• Owner: microsoft
• License: mit
• Created: 2022-04-06T07:01:38.000Z (over 2 years ago)
• Default Branch: main
• Last Pushed: 2024-07-26T20:44:37.000Z (3 months ago)
• Last Synced: 2024-07-26T22:22:33.766Z (3 months ago)
• Language: Python
• Homepage: https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter
• Size: 877 KB
• Stars: 146
• Watchers: 11
• Forks: 35
• Open Issues: 17
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md
  • Security: SECURITY.md
  • Support: SUPPORT.md

Awesome Lists containing this project

• stars - microsoft/vscode-black-formatter - Formatting support for Python using the Black formatter (Python)
• stars - microsoft/vscode-black-formatter - Formatting support for Python using the Black formatter (Python)

README

        
# Formatter extension for Visual Studio Code using the Black formatter

A Visual Studio Code extension with support for the Black formatter. The extension ships with `black=24.4.2`.

> Note: The minimum version of Black this extension supports is `22.3.0`.

This extension includes support for all [actively supported versions](https://devguide.python.org/#status-of-python-branches) of the Python language (i.e., Python >= 3.8).

For more information on the Black formatter, see https://black.readthedocs.io/en/stable/.

## Usage and Features

The Black extension for Visual Studio Code provides formatting support for your Python files. Check out the [Settings section](#settings) for more details on how to customize the extension.

-   **Integrated formatting**: Once this extension is installed in VS Code, Black will be automatically available as a formatter for Python. This is because the extension ships with a Black binary. You can ensure VS Code uses Black by default for all your Python files by setting the following in your User settings (**View** > **Command Palette...** and run **Preferences: Open User Settings (JSON)**):

    ```json

      "[python]": {

        "editor.defaultFormatter": "ms-python.black-formatter"

      }

    ```

-   **Format on save**: Automatically format your Python files on save by setting the `editor.formatOnSave` setting to `true` and the `editor.defaultFormatter` setting to `ms-python.black-formatter`. You can also enable format on save for Python files only by adding the following to your settings:

    ```json

      "[python]": {

        "editor.defaultFormatter": "ms-python.black-formatter",

        "editor.formatOnSave": true

      }

    ```

-   **Customize Black**: You can customize the behavior of Black by setting the `black-formatter.args` setting.

### Disabling formatting with Black

If you want to disable Black formatter, you can [disable this extension](https://code.visualstudio.com/docs/editor/extension-marketplace#_disable-an-extension) per workspace in Visual Studio Code.

## Settings

There are several settings you can configure to customize the behavior of this extension.

  

    

      Settings

      Default

      Description

    

  

  

    

      black-formatter.args

      []

      Arguments passed to Black to format Python files. Each argument should be provided as a separate string in the array. E.g "black-formatter.args" = ["--config", "<file>"]

    

    

      black-formatter.cwd

      []

      Sets the current working directory used to format Python files with Black. By default, it uses the root directory of the workspace ${workspaceFolder}. You can set it to ${fileDirname} to use the parent folder of the file being formatted as the working directory for Black.

    

    

      black-formatter.path

      []

      Path or command to be used by the extension to format Python files with Black. Accepts an array of a single or multiple strings. If passing a command, each argument should be provided as a separate string in the array. If set to ["black"], it will use the version of Black available in the PATH environment variable. Note: Using this option may slowdown formatting. 
 Examples: 
 ["~/global_env/black"] 
 ["conda", "run", "-n", "lint_env", "python", "-m", "black"]

    

    

      black-formatter.interpreter

      []

      Path to a Python executable or a command that will be used to launch the Black server and any subprocess. Accepts an array of a single or multiple strings. When set to [], the extension will use the path to the selected Python interpreter. If passing a command, each argument should be provided as a separate string in the array.

    

    

      black-formatter.importStrategy

      useBundled

      

      Defines which Black formatter binary to be used to format Python files. When set to useBundled, the extension will use the Black formatter binary that is shipped with the extension. When set to fromEnvironment, the extension will attempt to use the Black formatter binary and all dependencies that are available in the currently selected environment. **Note**: If the extension can't find a valid Black formatter binary in the selected environment, it will fallback to using the binary that is shipped with the extension. The black-formatter.path setting takes precedence and overrides the behavior of black-formatter.importStrategy.

      

    

    

      black-formatter.showNotification

      off

       Controls when notifications are shown by this extension.  Accepted values are onError, onWarning, always and off.

    

    

      black-formatter.serverTransport

      stdio

       Selects the transport protocol to be used by the Black server. When set to stdio, the extension will use the standard input/output streams to communicate with the Black server. When set to pipe, the extension will use a named pipe (on Windows) or Unix Domain Socket (on Linux/Mac) to communicate with the Black server. The stdio transport protocol is the default and recommended option for most users.

    

  

## Commands

  

    

      Command

      Description

    

  

  

    

      Black Formatter: Restart

      Force re-start the format server.

    

  

## Logging

From the Command Palette (**View** > **Command Palette ...**), run the **Developer: Set Log Level...** command. Select **Black Formatter** from the **Extension logs** group. Then select the log level you want to set.

Alternatively, you can set the `black-formatter.trace.server` setting to `verbose` to get more detailed logs from the Black server. This can be helpful when filing bug reports.

To open the logs, click on the language status icon (`{}`) on the bottom right of the Status bar, next to the Python language mode. Locate the **Black Formatter** entry and select **Open logs**.

## Troubleshooting

In this section, you will find some common issues you might encounter and how to resolve them. If you are experiencing any issues that are not covered here, please [file an issue](https://github.com/microsoft/vscode-black-formatter/issues).

-   If the `black-formatter.importStrategy` setting is set to `fromEnvironment` but Black is not found in the selected environment, this extension will fallback to using the Black binary that is shipped with the extension. However, if there are dependencies installed in the environment, those dependencies will be used along with the shipped Black binary. This can lead to problems if the dependencies are not compatible with the shipped Black binary.

    To resolve this issue, you can:

    -   Set the `black-formatter.importStrategy` setting to `useBundled` and the `black-formatter.path` setting to point to the custom binary of Black you want to use; or

    -   Install Black in the selected environment.