0
# Python LSP Server
1

2
A comprehensive Python implementation of the Language Server Protocol that provides advanced code intelligence features for Python development. The server offers completion, definitions, hover information, references, signature help, symbols, linting, formatting, and extensive plugin architecture for extending functionality across multiple editors and IDEs.
3

4
## Package Information
5

6
- **Package Name**: python-lsp-server
7
- **Language**: Python
8
- **Installation**: `pip install python-lsp-server`
9
- **Entry Point**: `pylsp` command-line interface
10

11
## Core Imports
12

13
```python
14
import pylsp
15
from pylsp import hookimpl, hookspec
16
from pylsp.python_lsp import PythonLSPServer
17
```
18

19
For plugin development:
20

21
```python
22
from pylsp import hookimpl
23
from pylsp.config.config import Config
24
from pylsp.workspace import Workspace, Document
25
```
26

27
## Basic Usage
28

29
### Command Line Interface
30

31
```bash
32
# Start server with stdio
33
pylsp
34

35
# Start TCP server
36
pylsp --tcp --host 127.0.0.1 --port 2087
37

38
# Start WebSocket server
39
pylsp --ws --port 2087
40

41
# Enable verbose logging
42
pylsp -v
43

44
# Use custom log configuration
45
pylsp --log-config /path/to/log_config.json
46
```
47

48
### Programmatic Server Usage
49

50
```python
51
from pylsp.python_lsp import (
52
    PythonLSPServer,
53
    start_io_lang_server,
54
    start_tcp_lang_server,
55
    start_ws_lang_server
56
)
57
import sys
58

59
# Start stdio server
60
stdin, stdout = sys.stdin.buffer, sys.stdout.buffer
61
start_io_lang_server(stdin, stdout, False, PythonLSPServer)
62

63
# Start TCP server
64
start_tcp_lang_server("127.0.0.1", 2087, False, PythonLSPServer)
65

66
# Start WebSocket server
67
start_ws_lang_server(2087, False, PythonLSPServer)
68
```
69

70
### Basic Plugin Development
71

72
```python
73
from pylsp import hookimpl
74

75
@hookimpl
76
def pylsp_lint(config, workspace, document, is_saved):
77
    """Provide custom linting diagnostics."""
78
    return [{
79
        "range": {
80
            "start": {"line": 0, "character": 0},
81
            "end": {"line": 0, "character": 10}
82
        },
83
        "message": "Custom diagnostic message",
84
        "severity": 1  # Error
85
    }]
86

87
@hookimpl
88
def pylsp_completions(config, workspace, document, position, ignored_names):
89
    """Provide custom completions."""
90
    return [{
91
        "label": "custom_function",
92
        "kind": 3,  # Function
93
        "detail": "Custom completion",
94
        "documentation": "A custom completion item"
95
    }]
96
```
97

98
## Architecture
99

100
The python-lsp-server is built on a modular plugin architecture using the Pluggy framework:
101

102
- **PythonLSPServer**: Core LSP server implementation handling protocol communication
103
- **Workspace**: Manages documents, configuration, and workspace-level operations
104
- **Document**: Represents individual files with Jedi integration for Python intelligence
105
- **Plugin System**: Pluggy-based hooks for extending functionality
106
- **Configuration**: Hierarchical configuration system supporting workspace and plugin-specific settings
107
- **Built-in Plugins**: Comprehensive set of plugins for linting, formatting, completion, and navigation
108

109
This architecture enables the server to provide consistent Python language intelligence while supporting extensive customization and third-party plugin development.
110

111
## Capabilities
112

113
### Server Management
114

115
Core server functionality including startup, configuration, and lifecycle management. Provides multiple server modes (stdio, TCP, WebSocket) and comprehensive CLI interface.
116

117
```python { .api }
118
def start_io_lang_server(rfile, wfile, check_parent_process, handler_class): ...
119
def start_tcp_lang_server(bind_addr, port, check_parent_process, handler_class): ...
120
def start_ws_lang_server(port, check_parent_process, handler_class): ...
121

122
class PythonLSPServer:
123
    def __init__(self, rx, tx, check_parent_process=False, consumer=None, *, endpoint_cls=None): ...
124
    def start(self): ...
125
    def capabilities(self): ...
126
```
127

128
[Server Management](./server-management.md)
129

130
### Plugin Development
131

132
Comprehensive plugin system using Pluggy hooks for extending server functionality. Provides 40+ hook specifications covering all LSP features and server lifecycle events.
133

134
```python { .api }
135
@hookimpl
136
def pylsp_lint(config, workspace, document, is_saved): ...
137
@hookimpl
138
def pylsp_completions(config, workspace, document, position, ignored_names): ...
139
@hookimpl
140
def pylsp_hover(config, workspace, document, position): ...
141
@hookimpl
142
def pylsp_definitions(config, workspace, document, position): ...
143
```
144

145
[Plugin Development](./plugin-development.md)
146

147
### Workspace Management
148

149
Document and workspace management with Jedi integration, configuration handling, and LSP workspace features including diagnostics publishing and progress reporting.
150

151
```python { .api }
152
class Workspace:
153
    def get_document(self, doc_uri): ...
154
    def put_document(self, doc_uri, source, version=None): ...
155
    def update_document(self, doc_uri, change, version=None): ...
156
    def publish_diagnostics(self, doc_uri, diagnostics, doc_version=None): ...
157
    def apply_edit(self, edit): ...
158

159
class Document:
160
    def jedi_script(self, position=None, use_document_path=False): ...
161
    def word_at_position(self, position): ...
162
    def offset_at_position(self, position): ...
163
```
164

165
[Workspace Management](./workspace-management.md)
166

167
### Configuration System
168

169
Hierarchical configuration system supporting workspace-level, plugin-specific, and document-specific settings with integration to external configuration files.
170

171
```python { .api }
172
class Config:
173
    def settings(self, document_path=None): ...
174
    def plugin_settings(self, plugin, document_path=None): ...
175
    def update(self, settings): ...
176
    def find_parents(self, path, names): ...
177
```
178

179
[Configuration System](./configuration-system.md)
180

181
### Utilities and Helpers
182

183
Comprehensive utility functions for LSP operations, text manipulation, URI handling, and Python-specific operations like path-to-module conversion.
184

185
```python { .api }
186
def debounce(interval_s, keyed_by=None): ...
187
def find_parents(root, path, names): ...
188
def format_docstring(contents, markup_kind, signatures=None, signature_config=None): ...
189
def to_fs_path(uri): ...
190
def from_fs_path(path): ...
191
```
192

193
[Utilities and Helpers](./utilities-helpers.md)