import-completer 0.6.2
A Python language server focused on intelligent import completions
Requires Python: >=3.13

# py-import-completer

> A Python language server focused on one thing: intelligent import completions

[![Python Version](https://img.shields.io/badge/python-3.13%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI](https://img.shields.io/badge/PyPI-import--completer-blue)](https://pypi.org/project/import-completer/)

![Image](https://github.com/user-attachments/assets/4bd3ecf6-d9d2-415e-a7d7-c883fec36bd7)

## The Problem

If you've worked with Python in editors like VS Code with Pylance, Neovim with Pyright, or other popular language servers, you've probably noticed something frustrating: **import completions are often incomplete or missing entirely**.

You're writing code and type `AsyncItera` expecting your editor to suggest `AsyncIterator` and auto-import it from `collections.abc`. Instead... nothing. You have to manually look up where the symbol is defined, type the import statement yourself, and then use it. This breaks your flow and slows you down.

Popular Python language servers excel at many things: type checking, go-to-definition, hover documentation, but they often fall short on import completions. This is where `py-import-completer` comes in.

## The Solution

`py-import-completer` is a lightweight Python language server that does **one thing and does it well**: providing import completions. When you start typing a symbol name, it:

1. Searches all available Python modules (stdlib, site-packages, your project)
2. Finds matching symbols (functions, classes, variables)
3. Suggests them as completions
4. **Automatically inserts the import statement** at the top of your file when you accept the completion

### How It Works

**Note**: This is a work in progress and some features are not complete yet or not working with full capacity.
CHeck out the [roadmap](#roadmap) for more details.

During startup, `py-import-completer` checks out your `python`'s `sys.path` to determine all the locations
of of third-party and project modules. Next, it uses `tree-sitter` to parse all Python files in your project
and extract all symbols (functions, classes, variables, etc.). Finally, it stores the extracted symbols in a
SQLite database for fast lookups. On any workspace files changes, it re-scans the affected files and rebuilds
the database (partially).

Server provides completions over standard LSP notifications, so it should work with any LSP client. Accepting
a completion will automatically insert the import statement in the imports section of the file
(always in new line, so you can use import organizer/code formatter to fix it later).

**Note**: This server provides **only** import completions. You should use it alongside other language server(s)
to get other features like type checking, go-to-definition, hover documentation, etc.

## Installation

### Prerequisites

- Python 3.13 or higher
- An LSP client (Neovim, VS Code, Helix, Emacs, etc.)

### Install from PyPI

The easiest way to install is via pip:

```bash
pip install import-completer
```

After installation, the `py-import-completer-server` command will be available.

### Install from Source

For development or the latest changes:

```bash
# Using uv (recommended)
git clone https://github.com/yourusername/py-import-completer.git
cd py-import-completer
uv sync

# Or using pip
pip install -e .
```

## Editor Setup

### Neovim

Choose the setup method based on your Neovim version:

#### Neovim 0.11+ (Recommended)

The modern approach using `vim.lsp.config()` and `vim.lsp.enable()`:

```lua
-- In your init.lua or LSP config file
vim.lsp.config('import_completer', {
  cmd = {'py-import-completer-server'},
  filetypes = {'python'},
  root_markers = {'pyproject.toml', 'setup.py', '.git'},
})

-- Enable the server (auto-activates in Python buffers)
vim.lsp.enable('import_completer')
```

This approach automatically activates the server in Python files when it detects a project root. No autocmd needed!

#### Neovim 0.8-0.10 (Legacy)

For older Neovim versions, use `vim.lsp.start()`:

```lua
-- In your LSP setup file (e.g., ~/.config/nvim/lua/lsp.lua)
vim.api.nvim_create_autocmd('FileType', {
  pattern = 'python',
  callback = function(args)
    vim.lsp.start({
      name = 'import_completer',
      cmd = {'py-import-completer-server'},
      root_dir = vim.fs.root(args.buf, {'setup.py', 'pyproject.toml'}),
    })
  end,
})
```

### Other Editors

`py-import-completer` implements the standard Language Server Protocol, so it should work with any LSP client. Here are some examples:

#### Helix

*Not tested (AI generated)*

Add to your `languages.toml`:

```toml
[language-server.py-import-completer]
command = "py-import-completer-server"

[[language]]
name = "python"
language-servers = ["py-import-completer", "pylsp"]  # Can combine with other servers
```

#### Emacs

*Not tested (AI generated)*

Using `eglot`:

```elisp
(add-to-list 'eglot-server-programs
             '(python-mode . ("py-import-completer-server")))
```

Or with `lsp-mode`, register the server similarly in your configuration.

#### Sublime Text

*Not tested (AI generated)*

Using the [LSP package](https://packagecontrol.io/packages/LSP), add to your LSP settings:

```json
{
  "clients": {
    "py-import-completer": {
      "enabled": true,
      "command": ["py-import-completer-server"],
      "selector": "source.python"
    }
  }
}
```

#### VS Code

*Not tested (AI generated)*

VS Code typically requires dedicated extensions for language servers. You can:
1. Create a simple extension wrapper (see [VS Code LSP documentation](https://code.visualstudio.com/api/language-extensions/language-server-extension-guide))

The server command is `py-import-completer-server` and it communicates via stdio.

## Configuration

Currently, `py-import-completer` automatically discovers Python modules from:
- **Standard library**: All stdlib modules
- **Site-packages**: Installed third-party packages
- **Current project**: Modules in your workspace

`py-import-completer` doesn't have to be installed in your current virtualenv. It will automatically checkout `sys.path`
of the `python` binary you're using (the first in your `$PATH`).

*No configuration options at the moment.*

## Known Limitations

`py-import-completer` is under active development. Current limitations include:

- **Top-level symbols only**: Nested classes and functions inside other symbols are not extracted
- **No dotted completions**: Only completes bare identifiers (e.g., `AsyncIterator`), not dotted names (e.g., `os.path`)
- **Single imports**: Each completion generates one import; no automatic import grouping
- **No relative imports**: Only handles absolute imports (`from module import symbol`)
- **In-memory database**: Symbol database is rebuilt on each server start (no persistence between sessions)
- **Limited configuration**: No configuration file support yet

These are all on the roadmap!

## Roadmap

*a.k.a. current limitations and caveats*

Planned features and improvements:

- [ ] Support for external stub (`*.pyi`) modules
- [ ] Use file SQLite database instead of in-memory, so symbols from third-party modules persist across sessions
- [x] Better inserting of import statements - currently it always inserts new line
      (you should be using import organizer/code formatter to fix this automatically)
- [x] Detection of already-imported-here symbols, so they don't show get re-imported every time
- [ ] Scanning for already used imports throughout the project, so they show up more often as suggestions
      (e.g. if you are already imported `Server` from library B elsewhere, it's probably a better suggestion than `Server` from library A)
- [ ] Configurable scoring system for completions (I have to make sure that this is actually possible in the LSP spec)
- [ ] Add configurable lookup paths (for some unusual scenarios and environments)
- [ ] Automated tests
- [ ] More configurable options in general
- [ ] Relative import support for intra-package imports

## Development

Contributions are welcome! Here's how to set up a development environment:

```bash
# Clone the repository
git clone https://github.com/yourusername/py-import-completer.git
cd py-import-completer

# Install dependencies with uv (recommended)
uv sync

# Or with pip
pip install -e .

# Run linting and formatting
ruff check .
ruff format .
```

### Project Structure

- `src/import_completer/`: Main source code
  - `language_server.py`: LSP server implementation
  - `completion_engine.py`: Core completion logic
  - `symbols_database.py`: SQLite symbol storage
  - `code_scanner.py`: Tree-sitter-based Python parser
  - `path_discovery.py`: Module path discovery utilities
  - `config.py`: Configuration management

## Contributing

Contributions are welcome! Please feel free to:

- Report bugs by opening an issue
- Suggest features or improvements
- Submit pull requests

Before submitting a PR, please ensure to follow pre-commit config (see [.pre-commit-config.yaml](.pre-commit-config.yaml)).

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Acknowledgments

Built with:
- [pygls](https://github.com/openlawlibrary/pygls) - Python Language Server framework
- [tree-sitter](https://tree-sitter.github.io/) - Incremental parsing library
- [tree-sitter-python](https://github.com/tree-sitter/tree-sitter-python) - Python grammar for tree-sitter