How To Use This Plugin¶

Simple Usage (Single Code Cell or File)¶

Assuming you have installed this plugin correctly, extra commands will be registered under the section of JUPYTERLAB CODE FORMATTER in the command palette, click on any of them to format whatever you were focused on.

Simple Usage (Selected Cells)¶

Highlight cells you want to format, then right click and select Format Cells.

Important

This uses the default formatter defined in config. See Changing Default Formatter for more info.

Simple Usage (Selected All Cells)¶

An extra button should appear in the toolbar (it should say Format Notebook when hovering over it), click that and the whole notebook will be formatted where possible.

Important

This uses the default formatter defined in config. See Changing Default Formatter for more info.

Keyboard Shortcuts¶

Scrolling down the command palette or clicking with the mouse is not efficient at all. To add to the available shortcuts, add something like the below to the shortcut section of the Advanced Setting Edtior of Jupyterlab.

{
    "shortcuts": [
        {
            "command": "jupyterlab_code_formatter:black",
            "keys": [
                "Ctrl K",
                "Ctrl M"
            ],
            "selector": ".jp-Notebook.jp-mod-editMode"
        }
    ]
}

The above example breaks down to

Under edit mode (detected through the selector);

Using the chord Ctrl+K Ctrl+M;

Invoke the jupyterlab_code_formatter:black command;

Other Available Commands¶

To find out what formatters are available, you can query http://localhost:8888/jupyterlab_code_formatter/formatters (you might need to replace the port and address), the keys of formatter are shown there.

To bind the format selected cells/format all cells command, the command to use would be jupyterlab_code_formatter:format and jupyterlab_code_formatter:format_all respectively.

Changing Default Formatter¶

To change the default formatter used the format action in context menu/toolbar (also jupyterlab_code_formatter:format and jupyterlab_code_formatter:format_all), go to “Settings” > “Advanced Settings Editor” > “Jupyterlab Code Formatter”, then in the “User Preferences” panel, enter, for example:

{
    "preferences": {
        "default_formatter": {
            "python": "autopep8",
            "R": "styler"
        }
    }
}

Chaining Default Formatters One After The Other¶

To invoke more than one formatters with invoking the commands jupyterlab_code_formatter:format and jupyterlab_code_formatter:format_all, one could configure the default formatter to be an array of strings like so:

{
    "preferences": {
        "default_formatter": {
            "python": ["isort", "black"],
            "R": ["styler", "formatR"],
        }
    }
}

Changing Formatter Parameter¶

There are also some formatter config exposed through the Jupyter Lab Advanced Settings Editor, have a browse and change it if you wish. for example:

{
    "autopep8": {
        "max_line_length": 120,
        "ignore": [
            "E226",
            "E302",
            "E41"
        ]
    }
}

Styler Configuration Example¶

The list construct is actually a JSON dictionary, to use math_token_spacing and reindention config, one would need to do something like the following.

{
    "styler": {
        "math_token_spacing": {
            "zero":["'^'"],
            "one":["'+'", "'-'", "'*'","'/'"]
        },
        "reindention": {
            "regex_pattern" : "^###",
            "indention" : 0,
            "comments_only" : true}
    }
}

Auto Format On Save¶

Go to Jupyter Lab Advanced Settings Editor, under Jupyterlab Code Formatter section, include the following key value pair.

{
    "formatOnSave": true
}