Starkiller

Work in progress

An import refactoring package and python-lsp-server plugin. Starkiller aims to be static, i.e. to analyse source code without actually executing it, and fast, thanks to built-in ast module.

The initial goal was to create a simple linter to get rid of star imports, hence the choice of the package name.

Using as a package

Starkiller can be used as a package for import refactoring. Each public method and class has a docstring explaining what it does and how to use it.

Python LSP Server plugin

The pylsp plugin provides the following code actions to refactor import statements:

• Replace * with explicit names - suggested for from ... import * statements.
• Replace * import with module import - suggested for from ... import * statements.
• Replace from import with module import - suggested for from ... import ... statements.
• Replace module import with from import - suggested for import ... statements.
• Remove unnecessary import - suggested for import statements with unused names.

To enable the plugin install Starkiller in the same virtual environment as python-lsp-server with [pylsp] optional dependency. E.g., with pipx:

pipx inject python-lsp-server starkiller[pylsp]

The plugin is enabled just the same way as any other pylsp plugin. E.g., in Neovim via lspconfig:

require("lspconfig").pylsp.setup {
    settings = {
        pylsp = {
            plugins = {
                starkiller = { enabled = true },
                aliases = {
                    numpy = "np",
                    [ "matplotlib.pyplot" ] = "plt",
                }
            }
        }
    }
}

Comma separated package imports

Multiple package imports like in the following example do not trigger any Code Actions right now:

import os, sys

This is hard to understand which import the user wants to fix here: os, sys or both. Splitting imports to different lines would help, but the user has to do it manually or with some other tool like Ruff. Starkiller is not a code formatter and should not handle import splitting.

At some point this might change. For example, a separate Code Action for each package could be suggested.

Alternatives and inspiration

• removestar is a Pyflakes based tool with similar objectives.
• SurpriseDog's scripts are a great source of inspiration.
• pylsp itself has a built-in rope_autoimport plugin utilizing Rope's autoimport module.