# python-lsp/python-lsp-server architecture

> Architecture diagram of the GitHub repository python-lsp/python-lsp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/python-lsp/python-lsp-server
- Repository: https://github.com/python-lsp/python-lsp-server

## Overview

##### Main Components
- Core LSP Server – Represented by the main executable (pylsp/__main__.py) and the LSP handling logic (pylsp/lsp.py). This is the central hub that accepts connections (over standard I/O, TCP, or WebSocket) and coordinates incoming requests from language clients.
- Plugins/subsystems – The pylsp/plugins directory contains various plugins (e.g., autopep8_format, flake8_lint, jedi_completion, etc.) that implement specific features like code formatting, linting, code completion, symbol resolution, etc. These plugins are dynamically loaded and contribute to the overall LSP functionality.
- Configuration Management – Modules in pylsp/config (including config.py, flake8_conf.py, pycodestyle_conf.py, and the schema.json) handle configuration settings. The architecture should highlight that configuration can be received from multiple sources (editor settings, setup.cfg files, and user configuration files).
- External Dependencies – Indicate integration with third-party libraries:
- Jedi for completions and analysis.
- Rope for refactoring and renaming functionalities.
- Various linters and code formatters (flake8, pycodestyle, autopep8, YAPF, etc.) that the server optionally integrates, based on available dependencies.
- Communication Interfaces – Illustrate how the server can operate either via standard IO or via WebSockets (mentioning that enabling websockets requires additional dependencies).

##### Relationships and Data Flow
- A language client (an IDE/editor) sends LSP requests (like auto-completion, hover, definition, etc.) that reach the Core LSP Server.
- The LSP Server parses the incoming requests and funnels them to the appropriate plugins (using the hookspecs mechanism visible in pylsp/hookspecs.py).
- Each plugin processes its equipped tasks (for example, performing linting, formatting, symbol lookup) and returns results to be packaged back to the client.
- Configuration flows into the server either from external configuration files (e.g., setup.cfg, .flake8, etc.) or directly from the client. The server then passes these settings to the relevant plugins.

##### Architectural Patterns & Design Principles
- Modularity – The system is partitioned into a central server component and discrete plugins. This makes it easier to extend functionality.
- Dependency Injection – External tools (Jedi, Rope, autopep8, etc.) are utilized by particular plugins, which allows for loose coupling between the core server logic and the external dependencies.
- Configurability – A layered configuration approach is employed where user settings, client-provided configurations, and workspace settings merge to determine behavior.
- Extensibility – The architecture uses a hook-based plugin system, which not only enables internal modularity but also third-party integrations (such as pylsp-mypy, python-lsp-isort, etc.).

##### Additional Elements
- Clear labels for each component: "Core LSP Server", "Plugins Manager", names of some example plugins (e.g., "jedi_completion", "flake8_lint", "autopep8_format"), and the "Configuration Manager".

## Diagram (Mermaid)

```mermaid
graph TD
    %% Nodes
    Client["External Client (IDE/Editor)"]:::client

    subgraph "Core LSP Server"
      CL1["Entry Point (__main__.py)"]:::server
      CL2["LSP Handling (lsp.py)"]:::server
    end

    Hooks["Hooks Specifications"]:::hooks

    subgraph "Plugins"
      PM["Plugin Manager"]:::plugin
      JEDI["jedi_completion"]:::plugin
      FLAKE["flake8_lint"]:::plugin
      AUTO["autopep8_format"]:::plugin
    end

    CONFIG["Configuration Manager"]:::config

    subgraph "External Dependencies"
      ED1["Jedi"]:::external
      ED2["Rope"]:::external
      ED3["autopep8"]:::external
      ED4["YAPF"]:::external
    end

    %% Data Flow Arrows
    Client -->|"LSPRequests"| CL1
    CL2 -->|"DispatchViaHooks"| Hooks
    Hooks -->|"RouteRequests"| PM
    PM -->|"Invoke"| JEDI
    PM -->|"Invoke"| FLAKE
    PM -->|"Invoke"| AUTO
    JEDI -->|"Uses"| ED1
    AUTO -->|"Uses"| ED3
    PM -->|"Utilizes"| ED2

    %% Configuration Flow
    CONFIG -->|"SuppliesConfig"| CL1
    CONFIG -->|"SuppliesConfig"| PM
    CONFIG -->|"SuppliesConfig"| AUTO

    %% Response Flow
    CL2 -->|"ReturnsResponse"| Client

    %% Click Events
    click CL1 "https://github.com/python-lsp/python-lsp-server/blob/develop/pylsp/__main__.py"
    click CL2 "https://github.com/python-lsp/python-lsp-server/blob/develop/pylsp/lsp.py"
    click PM "https://github.com/python-lsp/python-lsp-server/tree/develop/pylsp/plugins"
    click JEDI "https://github.com/python-lsp/python-lsp-server/blob/develop/pylsp/plugins/jedi_completion.py"
    click FLAKE "https://github.com/python-lsp/python-lsp-server/blob/develop/pylsp/plugins/flake8_lint.py"
    click AUTO "https://github.com/python-lsp/python-lsp-server/blob/develop/pylsp/plugins/autopep8_format.py"
    click CONFIG "https://github.com/python-lsp/python-lsp-server/tree/develop/pylsp/config"
    click Hooks "https://github.com/python-lsp/python-lsp-server/blob/develop/pylsp/hookspecs.py"

    %% Styles
    classDef server fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef client fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef plugin fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef config fill:#F5CBA7,stroke:#D35400,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef hooks fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
```
