0
# Server Management
1
2
Core server functionality for starting, configuring, and managing the Python LSP Server. Provides multiple communication modes and comprehensive command-line interface for different deployment scenarios.
3
4
## Capabilities
5
6
### Server Startup Functions
7
8
Functions for starting the LSP server in different communication modes (stdio, TCP, WebSocket).
9
10
```python { .api }
11
def start_io_lang_server(rfile, wfile, check_parent_process, handler_class):
12
"""
13
Start LSP server using stdio streams.
14
15
Parameters:
16
- rfile: readable stream for input
17
- wfile: writable stream for output
18
- check_parent_process: bool, auto-shutdown when parent dies
19
- handler_class: PythonLSPServer class or subclass
20
"""
21
22
def start_tcp_lang_server(bind_addr, port, check_parent_process, handler_class):
23
"""
24
Start LSP server using TCP socket.
25
26
Parameters:
27
- bind_addr: str, IP address to bind to
28
- port: int, port number to bind to
29
- check_parent_process: bool, auto-shutdown when parent dies
30
- handler_class: PythonLSPServer class or subclass
31
"""
32
33
def start_ws_lang_server(port, check_parent_process, handler_class):
34
"""
35
Start LSP server using WebSocket.
36
37
Requires 'python-lsp-server[websockets]' installation for websockets support.
38
Uses asyncio with ThreadPoolExecutor for concurrent message processing.
39
40
Parameters:
41
- port: int, port number for WebSocket server
42
- check_parent_process: bool, auto-shutdown when parent dies
43
- handler_class: PythonLSPServer class or subclass
44
45
Raises:
46
- ImportError: if websockets package not installed
47
"""
48
```
49
50
### PythonLSPServer Class
51
52
Main LSP server implementation handling protocol communication and request dispatching.
53
54
```python { .api }
55
class PythonLSPServer:
56
def __init__(self, rx, tx, check_parent_process=False, consumer=None, *, endpoint_cls=None):
57
"""
58
Initialize LSP server.
59
60
Parameters:
61
- rx: readable stream for input
62
- tx: writable stream for output
63
- check_parent_process: bool, monitor parent process
64
- consumer: optional message consumer
65
- endpoint_cls: optional endpoint class override
66
"""
67
68
def start(self):
69
"""Start the server and begin processing requests."""
70
71
def consume(self, message):
72
"""
73
Process a single LSP message.
74
75
Parameters:
76
- message: dict, LSP message to process
77
"""
78
79
def capabilities(self):
80
"""
81
Return server capabilities.
82
83
Returns:
84
dict: LSP server capabilities
85
"""
86
```
87
88
### Command Line Interface
89
90
Main CLI entry point and argument configuration.
91
92
```python { .api }
93
def main():
94
"""Main CLI entry point."""
95
96
def add_arguments(parser):
97
"""
98
Add command-line arguments to ArgumentParser.
99
100
Parameters:
101
- parser: argparse.ArgumentParser instance
102
"""
103
```
104
105
#### CLI Arguments
106
107
- `--tcp`: Use TCP server instead of stdio
108
- `--ws`: Use WebSocket server instead of stdio
109
- `--host`: Bind address (default: 127.0.0.1)
110
- `--port`: Port number (default: 2087)
111
- `--check-parent-process`: Auto-shutdown when parent process dies
112
- `--log-config`: Path to JSON logging configuration file
113
- `--log-file`: Redirect logs to file instead of stderr
114
- `-v/--verbose`: Increase verbosity (can be repeated)
115
- `-V/--version`: Show version information
116
117
### Constants
118
119
Server configuration constants.
120
121
```python { .api }
122
LINT_DEBOUNCE_S = 0.5 # Lint debounce interval in seconds
123
PARENT_PROCESS_WATCH_INTERVAL = 10 # Parent process check interval
124
MAX_WORKERS = 64 # Maximum worker threads
125
PYTHON_FILE_EXTENSIONS = (".py", ".pyi") # Supported file extensions
126
CONFIG_FILEs = ("pycodestyle.cfg", "setup.cfg", "tox.ini", ".flake8") # Config files
127
```
128
129
## Usage Examples
130
131
### Basic Server Startup
132
133
```python
134
from pylsp.python_lsp import PythonLSPServer, start_io_lang_server
135
import sys
136
137
# Start with stdio
138
stdin, stdout = sys.stdin.buffer, sys.stdout.buffer
139
start_io_lang_server(stdin, stdout, False, PythonLSPServer)
140
```
141
142
### TCP Server with Custom Configuration
143
144
```python
145
from pylsp.python_lsp import start_tcp_lang_server, PythonLSPServer
146
147
# Custom server class with additional functionality
148
class CustomLSPServer(PythonLSPServer):
149
def __init__(self, *args, **kwargs):
150
super().__init__(*args, **kwargs)
151
# Custom initialization
152
153
# Start TCP server
154
start_tcp_lang_server("0.0.0.0", 8080, True, CustomLSPServer)
155
```
156
157
### WebSocket Server
158
159
```python
160
from pylsp.python_lsp import start_ws_lang_server, PythonLSPServer
161
162
# Requires websockets package: pip install 'python-lsp-server[websockets]'
163
# Uses asyncio event loop with ThreadPoolExecutor (max_workers=10)
164
# Handles multiple concurrent WebSocket connections
165
try:
166
start_ws_lang_server(2087, False, PythonLSPServer)
167
except ImportError as e:
168
print("WebSocket support not available. Install with: pip install 'python-lsp-server[websockets]'")
169
```
170
171
WebSocket server architecture:
172
- Uses `websockets` library for WebSocket protocol handling
173
- Employs `ThreadPoolExecutor` with 10 max workers for request processing
174
- Each WebSocket connection runs in async event loop
175
- JSON-RPC messages are processed in thread pool to avoid blocking
176
- Response handler sends processed results back through WebSocket connection
177
178
### Command Line Usage
179
180
```bash
181
# Basic stdio server
182
pylsp
183
184
# TCP server with verbose logging
185
pylsp --tcp --host 0.0.0.0 --port 8080 -vv
186
187
# WebSocket server with custom log file
188
pylsp --ws --port 2087 --log-file /var/log/pylsp.log
189
190
# Server with parent process monitoring
191
pylsp --check-parent-process
192
```