# Python Lsp Server

> This server can be configured using the`workspace/didChangeConfiguration`method. Each configuration option is described below. Note, a value of`null`means that we do not set a value and thus use t

---

# Source: https://github.com/python-lsp/python-lsp-server/blob/develop/CONFIGURATION.md

# Python Language Server Configuration
This server can be configured using the `workspace/didChangeConfiguration` method. Each configuration option is described below. Note, a value of `null` means that we do not set a value and thus use the plugin's default value.

| **Configuration Key** | **Type** | **Description** | **Default** 
|----|----|----|----|
| `pylsp.configurationSources` | `array` of unique `string` (one of: `'pycodestyle'`, `'flake8'`) items | List of configuration sources to use. | `["pycodestyle"]` |
| `pylsp.plugins.autopep8.enabled` | `boolean` | Enable or disable the plugin (disabling required to use `yapf`). | `true` |
| `pylsp.plugins.flake8.config` | `string` | Path to the config file that will be the authoritative config source. | `null` |
| `pylsp.plugins.flake8.enabled` | `boolean` | Enable or disable the plugin. | `false` |
| `pylsp.plugins.flake8.exclude` | `array` of `string` items | List of files or directories to exclude. | `[]` |
| `pylsp.plugins.flake8.extendIgnore` | `array` of `string` items | List of errors and warnings to append to ignore list. | `[]` |
| `pylsp.plugins.flake8.extendSelect` | `array` of `string` items | List of errors and warnings to append to select list. | `[]` |
| `pylsp.plugins.flake8.executable` | `string` | Path to the flake8 executable. | `"flake8"` |
| `pylsp.plugins.flake8.filename` | `string` | Only check for filenames matching the patterns in this list. | `null` |
| `pylsp.plugins.flake8.hangClosing` | `boolean` | Hang closing bracket instead of matching indentation of opening bracket's line. | `null` |
| `pylsp.plugins.flake8.ignore` | `array` of `string` items | List of errors and warnings to ignore (or skip). | `[]` |
| `pylsp.plugins.flake8.maxComplexity` | `integer` | Maximum allowed complexity threshold. | `null` |
| `pylsp.plugins.flake8.maxLineLength` | `integer` | Maximum allowed line length for the entirety of this run. | `null` |
| `pylsp.plugins.flake8.indentSize` | `integer` | Set indentation spaces. | `null` |
| `pylsp.plugins.flake8.perFileIgnores` | `array` of `string` items | A pairing of filenames and violation codes that defines which violations to ignore in a particular file, for example: `["file_path.py:W305,W304"]`). | `[]` |
| `pylsp.plugins.flake8.select` | `array` of unique `string` items | List of errors and warnings to enable. | `null` |
| `pylsp.plugins.jedi.auto_import_modules` | `array` of `string` items | List of module names for jedi.settings.auto_import_modules. | `["numpy"]` |
| `pylsp.plugins.jedi.extra_paths` | `array` of `string` items | Define extra paths for jedi.Script. | `[]` |
| `pylsp.plugins.jedi.prioritize_extra_paths` | `boolean` | Whether to place extra_paths at the beginning (true) or end (false) of `sys.path` | `false` |
| `pylsp.plugins.jedi.env_vars` | `object` | Define environment variables for jedi.Script and Jedi.names. | `null` |
| `pylsp.plugins.jedi.environment` | `string` | Define environment for jedi.Script and Jedi.names. | `null` |
| `pylsp.plugins.jedi_completion.enabled` | `boolean` | Enable or disable the plugin. | `true` |
| `pylsp.plugins.jedi_completion.include_params` | `boolean` | Auto-completes methods and classes with tabstops for each parameter. | `true` |
| `pylsp.plugins.jedi_completion.include_class_objects` | `boolean` | Adds class objects as a separate completion item. | `false` |
| `pylsp.plugins.jedi_completion.include_function_objects` | `boolean` | Adds function objects as a separate completion item. | `false` |
| `pylsp.plugins.jedi_completion.fuzzy` | `boolean` | Enable fuzzy when requesting autocomplete. | `false` |
| `pylsp.plugins.jedi_completion.eager` | `boolean` | Resolve documentation and detail eagerly. | `false` |
| `pylsp.plugins.jedi_completion.resolve_at_most` | `integer` | How many labels and snippets (at most) should be resolved? | `25` |
| `pylsp.plugins.jedi_completion.cache_for` | `array` of `string` items | Modules for which labels and snippets should be cached. | `["pandas", "numpy", "tensorflow", "matplotlib"]` |
| `pylsp.plugins.jedi_definition.enabled` | `boolean` | Enable or disable the plugin. | `true` |
| `pylsp.plugins.jedi_definition.follow_imports` | `boolean` | The goto call will follow imports. | `true` |
| `pylsp.plugins.jedi_definition.follow_builtin_imports` | `boolean` | If follow_imports is True will decide if it follow builtin imports. | `true` |
| `pylsp.plugins.jedi_definition.follow_builtin_definitions` | `boolean` | Follow builtin and extension definitions to stubs. | `true` |
| `pylsp.plugins.jedi_hover.enabled` | `boolean` | Enable or disable the plugin. | `true` |
| `pylsp.plugins.jedi_references.enabled` | `boolean` | Enable or disable the plugin. | `true` |
| `pylsp.plugins.jedi_signature_help.enabled` | `boolean` | Enable or disable the plugin. | `true` |
| `pylsp.plugins.jedi_symbols.enabled` | `boolean` | Enable or disable the plugin. | `true` |
| `pylsp.plugins.jedi_symbols.all_scopes` | `boolean` | If True lists the names of all scopes instead of only the module namespace. | `true` |
| `pylsp.plugins.jedi_symbols.include_import_symbols` | `boolean` | If True includes symbols imported from other libraries. | `true` |
| `pylsp.plugins.jedi_type_definition.enabled` | `boolean` | Enable or disable the plugin. | `true` |
| `pylsp.plugins.mccabe.enabled` | `boolean` | Enable or disable the plugin. | `true` |
| `pylsp.plugins.mccabe.threshold` | `integer` | The minimum threshold that triggers warnings about cyclomatic complexity. | `15` |
| `pylsp.plugins.preload.enabled` | `boolean` | Enable or disable the plugin. | `true` |
| `pylsp.plugins.preload.modules` | `array` of unique `string` items | List of modules to import on startup | `[]` |
| `pylsp.plugins.pycodestyle.enabled` | `boolean` | Enable or disable the plugin. | `true` |
| `pylsp.plugins.pycodestyle.exclude` | `array` of unique `string` items | Exclude files or directories which match these patterns. | `[]` |
| `pylsp.plugins.pycodestyle.filename` | `array` of unique `string` items | When parsing directories, only check filenames matching these patterns. | `[]` |
| `pylsp.plugins.pycodestyle.select` | `array` of unique `string` items | Select errors and warnings | `null` |
| `pylsp.plugins.pycodestyle.ignore` | `array` of unique `string` items | Ignore errors and warnings | `[]` |
| `pylsp.plugins.pycodestyle.hangClosing` | `boolean` | Hang closing bracket instead of matching indentation of opening bracket's line. | `null` |
| `pylsp.plugins.pycodestyle.maxLineLength` | `integer` | Set maximum allowed line length. | `null` |
| `pylsp.plugins.pycodestyle.indentSize` | `integer` | Set indentation spaces. | `null` |
| `pylsp.plugins.pydocstyle.enabled` | `boolean` | Enable or disable the plugin. | `false` |
| `pylsp.plugins.pydocstyle.convention` | `string` (one of: `'pep257'`, `'numpy'`, `'google'`, `None`) | Choose the basic list of checked errors by specifying an existing convention. | `null` |
| `pylsp.plugins.pydocstyle.addIgnore` | `array` of unique `string` items | Ignore errors and warnings in addition to the specified convention. | `[]` |
| `pylsp.plugins.pydocstyle.addSelect` | `array` of unique `string` items | Select errors and warnings in addition to the specified convention. | `[]` |
| `pylsp.plugins.pydocstyle.ignore` | `array` of unique `string` items | Ignore errors and warnings | `[]` |
| `pylsp.plugins.pydocstyle.select` | `array` of unique `string` items | Select errors and warnings | `null` |
| `pylsp.plugins.pydocstyle.match` | `string` | Check only files that exactly match the given regular expression; default is to match files that don't start with 'test_' but end with '.py'. | `"(?!test_).*\\.py"` |
| `pylsp.plugins.pydocstyle.matchDir` | `string` | Search only dirs that exactly match the given regular expression; default is to match dirs which do not begin with a dot. | `"[^\\.].*"` |
| `pylsp.plugins.pyflakes.enabled` | `boolean` | Enable or disable the plugin. | `true` |
| `pylsp.plugins.pylint.enabled` | `boolean` | Enable or disable the plugin. | `false` |
| `pylsp.plugins.pylint.args` | `array` of non-unique `string` items | Arguments to pass to pylint. | `[]` |
| `pylsp.plugins.pylint.executable` | `string` | Executable to run pylint with. Enabling this will run pylint on unsaved files via stdin. Can slow down workflow. Only works with python3. | `null` |
| `pylsp.plugins.rope_autoimport.enabled` | `boolean` | Enable or disable autoimport. If false, neither completions nor code actions are enabled. If true, the respective features can be enabled or disabled individually. | `false` |
| `pylsp.plugins.rope_autoimport.completions.enabled` | `boolean` | Enable or disable autoimport completions. | `true` |
| `pylsp.plugins.rope_autoimport.code_actions.enabled` | `boolean` | Enable or disable autoimport code actions (e.g. for quick fixes). | `true` |
| `pylsp.plugins.rope_autoimport.memory` | `boolean` | Make the autoimport database memory only. Drastically increases startup time. | `false` |
| `pylsp.plugins.rope_completion.enabled` | `boolean` | Enable or disable the plugin. | `false` |
| `pylsp.plugins.rope_completion.eager` | `boolean` | Resolve documentation and detail eagerly. | `false` |
| `pylsp.plugins.yapf.enabled` | `boolean` | Enable or disable the plugin. | `true` |
| `pylsp.rope.extensionModules` | `string` | Builtin and c-extension modules that are allowed to be imported and inspected by rope. | `null` |
| `pylsp.rope.ropeFolder` | `array` of unique `string` items | The name of the folder in which rope stores project configurations and data.  Pass `null` for not using such a folder at all. | `null` |
| `pylsp.signature.formatter` | `string` (one of: `'black'`, `'ruff'`, `None`) | Formatter to use for reformatting signatures in docstrings. | `"black"` |
| `pylsp.signature.include_docstring` | `boolean` | Include signature docstring. | `true` |
| `pylsp.signature.line_length` | `number`  | Maximum line length in signatures. | `88` |

This documentation was generated from `pylsp/config/schema.json`. Please do not edit this file directly.

---

# Source: https://github.com/python-lsp/python-lsp-server/tree/develop/pylsp/plugins

# Python LSP Server - Plugin System Guide

This document describes the built-in plugins available in python-lsp-server.

## Available Plugins

### flake8_lint.py
Flake8 integration plugin for linting Python code with flake8.

**Configuration Keys:**
- `pylsp.plugins.flake8.enabled` - Enable/disable flake8 plugin (default: false)
- `pylsp.plugins.flake8.config` - Path to .flake8 config file
- `pylsp.plugins.flake8.exclude` - Exclude patterns
- `pylsp.plugins.flake8.extendIgnore` - Error codes to ignore
- `pylsp.plugins.flake8.extendSelect` - Error codes to select
- `pylsp.plugins.flake8.executable` - Path to flake8 executable
- `pylsp.plugins.flake8.filename` - Filename patterns to check
- `pylsp.plugins.flake8.hangClosing` - Hang closing bracket
- `pylsp.plugins.flake8.ignore` - Error codes to ignore
- `pylsp.plugins.flake8.maxComplexity` - Max cyclomatic complexity
- `pylsp.plugins.flake8.maxLineLength` - Max line length
- `pylsp.plugins.flake8.indentSize` - Indentation size
- `pylsp.plugins.flake8.perFileIgnores` - Per-file ignore rules
- `pylsp.plugins.flake8.select` - Error codes to select

### Other Built-in Plugins
- autopep8 - Auto-formatting with autopep8
- jedi - Code completion with jedi
- mccabe - McCabe complexity checking
- pycodestyle - PEP 8 style checking
- pylint - Linting with pylint
- rope - Refactoring support with rope

## Plugin Configuration

Configuration is managed via Language Server Protocol's `workspace/didChangeConfiguration` method.
Typical configuration locations:
1. `.pylsp.cfg` or `.pylsprc`
2. `setup.cfg`
3. `pyproject.toml`
4. Language server client settings

## Example Configuration

```json
{
  "pylsp": {
    "plugins": {
      "flake8": {
        "enabled": true,
        "maxLineLength": 100,
        "ignore": ["E501", "W503"]
      }
    },
    "configurationSources": ["flake8"]
  }
}
```

## Plugin Development

Plugins can be created by implementing the `PylspPlugin` interface and registering
as a setuptools entry point in the `pylsp_plugins` group.

For details, see the source code at: https://github.com/python-lsp/python-lsp-server/tree/develop/pylsp/plugins

---

# Source: https://github.com/python-lsp/python-lsp-server/blob/develop/pylsp/plugins/flake8_lint.py

# pylsp-flake8: Flake8 Integration for Python LSP Server

## Overview

**pylsp-flake8** is the built-in flake8 plugin for **python-lsp-server** (formerly python-language-server). It integrates the popular [flake8](https://flake8.pycqa.org/) linter into your Language Server Protocol (LSP) client, enabling real-time Python code linting and diagnostics.

Unlike standalone flake8, pylsp-flake8 provides:
- Real-time linting feedback in LSP-compatible editors (VS Code, Vim, Neovim, Emacs, etc.)
- Configuration via Language Server settings (no separate .flake8 config needed)
- Integration with other python-lsp-server plugins
- Customizable error filtering and complexity thresholds

## What is flake8?

[Flake8](https://flake8.pycqa.org/) is a Python linter that combines three tools:
1. **PyCodeStyle** (PEP 8) - Style guide enforcement
2. **Pyflakes** - Logical errors detection (undefined names, unused imports)
3. **McCabe** - Cyclomatic complexity checking

## Installation

### Prerequisites

- Python 3.7 or later
- python-lsp-server installed

```bash
# Install python-lsp-server (includes flake8 plugin)
pip install python-lsp-server

# Or install with flake8 explicitly
pip install python-lsp-server[flake8]

# Flake8 and dependencies will be installed automatically
```

### Standalone Flake8 Installation

If flake8 is not installed, you can install it separately:

```bash
pip install flake8
```

## Configuration

### Enable/Disable the Plugin

By default, flake8 is disabled in python-lsp-server (pycodestyle is enabled instead). To enable flake8:

**VS Code example (.vscode/settings.json):**
```json
{
  "pylsp": {
    "plugins": {
      "flake8": {
        "enabled": true
      },
      "pycodestyle": {
        "enabled": false
      }
    }
  }
}
```

**Neovim/Vim example (via nvim-lspconfig or vim-lsp):**
```lua
-- lua configuration
require('lspconfig').pylsp.setup{
  settings = {
    pylsp = {
      plugins = {
        flake8 = { enabled = true },
        pycodestyle = { enabled = false }
      }
    }
  }
}
```

### Configuration Options

All flake8 plugin settings are under `pylsp.plugins.flake8.*`:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `false` | Enable/disable the flake8 plugin |
| `config` | string | `null` | Path to .flake8, setup.cfg, or tox.ini config file |
| `ignore` | array | `[]` | Error codes to ignore (e.g., `["E501", "W503"]`) |
| `select` | array | `null` | Only check these error codes (whitelist) |
| `extendIgnore` | array | `[]` | Additional codes to ignore (appended to `ignore`) |
| `extendSelect` | array | `[]` | Additional codes to select (appended to `select`) |
| `exclude` | array | `[]` | Patterns to exclude from checking |
| `executable` | string | `"flake8"` | Path to flake8 executable |
| `filename` | string | `null` | Filename patterns to check |
| `maxLineLength` | integer | `null` | Maximum line length (E501) |
| `maxComplexity` | integer | `null` | Maximum cyclomatic complexity (C901) |
| `hangClosing` | boolean | `null` | Hang closing bracket in formatting |
| `indentSize` | integer | `null` | Indentation size in spaces |
| `perFileIgnores` | array | `[]` | Per-file ignore patterns (e.g., `["test_*.py:F401"]`) |

### Example Configurations

**Strict Style Checking:**
```json
{
  "pylsp": {
    "plugins": {
      "flake8": {
        "enabled": true,
        "maxLineLength": 88,
        "ignore": ["W503"]
      }
    }
  }
}
```

**Relaxed Checking (Common for Data Science):**
```json
{
  "pylsp": {
    "plugins": {
      "flake8": {
        "enabled": true,
        "maxLineLength": 120,
        "ignore": ["E501", "W503", "E703", "E231"]
      }
    }
  }
}
```

**Per-File Ignores:**
```json
{
  "pylsp": {
    "plugins": {
      "flake8": {
        "enabled": true,
        "perFileIgnores": [
          "__init__.py:F401",
          "tests/*:F841,E501"
        ]
      }
    }
  }
}
```

## Using External Configuration Files

Instead of inline settings, you can use flake8's standard config files:

### .flake8 File

```ini
[flake8]
max-line-length = 100
exclude = .git,__pycache__,build,dist
ignore = E501,W503
```

### setup.cfg File

```ini
[flake8]
max-line-length = 100
exclude = .git,__pycache__,build,dist
ignore = E501,W503
```

### pyproject.toml File

```toml
[tool.flake8]
max-line-length = 100
exclude = [".git", "__pycache__", "build", "dist"]
ignore = ["E501", "W503"]
```

### Tell python-lsp-server to Use Config File

```json
{
  "pylsp": {
    "plugins": {
      "flake8": {
        "enabled": true,
        "config": "/path/to/.flake8"
      }
    },
    "configurationSources": ["flake8"]
  }
}
```

## Common Flake8 Error Codes

| Code | Tool | Description | Example |
|------|------|-------------|---------|
| **E*** | pycodestyle | Style issues | E501 (line too long) |
| **W*** | pycodestyle | Warnings | W503 (line break before binary operator) |
| **F*** | pyflakes | Undefined/unused names | F401 (unused import) |
| **C901** | mccabe | Complexity too high | Function has complexity > threshold |

### Common Ignores

- **E501** - Line too long (conflicts with formatting tools like Black)
- **W503** - Line break before binary operator (PEP 8 opinion changed)
- **E203** - Whitespace before ':' (conflicts with Black)
- **F401** - Unused imports in `__init__.py` files
- **E731** - Lambda assignment (sometimes intentional)

## Usage in Different Editors

### VS Code

Install the **Pylance** extension or **Python** extension with LSP support:

```json
{
  "python.linting.enabled": true,
  "python.linting.lspNotebookCellExecutionOrder": ["python"],
  "[python]": {
    "defaultInterpreterPath": "${workspaceFolder}/venv/bin/python"
  },
  "pylsp": {
    "plugins": {
      "flake8": {
        "enabled": true
      }
    }
  }
}
```

### Neovim

Use **nvim-lspconfig** with python-lsp-server:

```lua
require('lspconfig').pylsp.setup {
  settings = {
    pylsp = {
      plugins = {
        flake8 = { enabled = true }
      }
    }
  }
}
```

### Vim

Use **vim-lsp** or **coc-nvim**:

```vim
" .vimrc - configure via language server initialization
let g:lsp_settings = {
  \ 'pylsp-all': {
  \   'workspace_config': {
  \     'pylsp': {
  \       'plugins': {
  \         'flake8': { 'enabled': 1 }
  \       }
  \     }
  \   }
  \ }
```

### Emacs

Use **lsp-mode** with **lsp-pylsp**:

```elisp
(use-package lsp-pylsp
  :ensure t
  :config
  (setq lsp-pylsp-plugins-flake8-enabled t))
```

## Troubleshooting

### Flake8 Plugin Not Working

1. **Check if enabled:**
   ```json
   { "pylsp": { "plugins": { "flake8": { "enabled": true } } } }
   ```

2. **Verify flake8 is installed:**
   ```bash
   python -m flake8 --version
   ```

3. **Check if pycodestyle is disabled** (they conflict):
   ```json
   { "pylsp": { "plugins": { "pycodestyle": { "enabled": false } } } }
   ```

4. **Verify LSP server is using correct Python:**
   ```bash
   # Check which python flake8 uses
   which flake8
   flake8 --version
   ```

### Missing Diagnostic Messages

- Check `.flake8` or `setup.cfg` doesn't exclude your file
- Verify error code is not in `ignore` list
- Check file extension is `.py` or matches `filename` pattern

### Performance Issues

- Large `maxComplexity` threshold reduces overhead
- Use `exclude` to skip large directories
- Consider using per-file ignores for test files

## Integration with Other Tools

### Combining with Black (Code Formatter)

Black and flake8 have some conflicting rules:

```json
{
  "pylsp": {
    "plugins": {
      "flake8": {
        "enabled": true,
        "maxLineLength": 88,
        "ignore": ["E501", "W503", "E203"]
      },
      "autopep8": {
        "enabled": false
      },
      "yapf": {
        "enabled": false
      }
    }
  }
}
```

### Combining with Pylint

Both flake8 and pylint can be enabled for comprehensive linting:

```json
{
  "pylsp": {
    "plugins": {
      "flake8": {
        "enabled": true
      },
      "pylint": {
        "enabled": true
      }
    }
  }
}
```

### Combining with isort (Import Sorter)

flake8 can check import order when combined with isort plugin:

```json
{
  "pylsp": {
    "plugins": {
      "flake8": {
        "enabled": true,
        "ignore": ["F401"]
      },
      "isort": {
        "enabled": true
      }
    }
  }
}
```

## Related Documentation

- **[python-lsp-server Repository](https://github.com/python-lsp/python-lsp-server)** - Main project
- **[flake8 Official Documentation](https://flake8.pycqa.org/)** - Complete flake8 reference
- **[PEP 8 Style Guide](https://www.python.org/dev/peps/pep-0008/)** - Python style conventions
- **[CONFIGURATION.md](./CONFIGURATION.md)** - Full python-lsp-server plugin configuration

## See Also

- **[pycodestyle plugin](./CONFIGURATION.md)** - Alternative PEP 8 checker
- **[pylint plugin](./CONFIGURATION.md)** - More comprehensive static analysis
- **[autopep8 plugin](./CONFIGURATION.md)** - Auto-formatting

## Version Information

- **python-lsp-server**: Maintains flake8 plugin for all recent versions
- **flake8**: Requires flake8 >= 3.0
- **Note**: pylsp-flake8 is NOT a separate package; it's built into python-lsp-server

To check your python-lsp-server version:
```bash
pip show python-lsp-server
```

To check your flake8 version:
```bash
flake8 --version
```

---

# Source: https://github.com/python-lsp/python-lsp-server/blob/develop/docs/autoimport.md

# Autoimport for pylsp

Requirements:

1. install `python-lsp-server[rope]`
2. set `pylsp.plugins.rope_autoimport.enabled` to `true`
3. This enables both completions and code actions. You can switch them off by setting `pylsp.plugins.rope_autoimport.completions.enabled` and/or `pylsp.plugins.rope_autoimport.code_actions.enabled` to `false`

## Startup

Autoimport will generate an autoimport sqllite3 database in .ropefolder/autoimport.db on startup.  
This will take a few seconds but should be much quicker on future runs.

## Usage

Autoimport will provide suggestions to import names from everything in `sys.path`. You can change this by changing where pylsp is running or by setting rope's 'python_path' option.
It will suggest modules, submodules, keywords, functions, and classes.

Since autoimport inserts everything towards the end of the import group, its recommended you use the isort [plugin](https://github.com/paradoxxxzero/pyls-isort).

## Credits

- Most of the code was written by me, @bagel897
- [lyz-code](https://github.com/lyz-code/autoimport) for inspiration and some ideas
- [rope](https://github.com/python-rope/rope), especially @lieryan
- [pyright](https://github.com/Microsoft/pyright) for details on language server implementation