Metadata-Version: 2.4
Name: sage-lsp
Version: 1.1.2
Summary: SageMath Language Server Protocol
Author-email: SeanDictionary <sean.dictionary@qq.com>
License-Expression: GPL-3.0
Project-URL: Homepage, https://github.com/SeanDictionary/sage-lsp
Project-URL: Issues, https://github.com/SeanDictionary/sage-lsp/issues
Project-URL: ChangeLog, https://github.com/SeanDictionary/sage-lsp/blob/main/CHANGELOG.md
Keywords: SageMath,Sage,LSP,Python
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pygls==2.0.0
Requires-Dist: pluggy==1.6.0
Requires-Dist: platformdirs==4.4.0
Requires-Dist: pycodestyle==2.14.0
Requires-Dist: autopep8==2.3.2
Requires-Dist: pyflakes==3.4.0
Requires-Dist: jedi==0.19.2
Requires-Dist: docstring-to-markdown==0.17
Dynamic: license-file

# sage-lsp

## Description

![Release](https://img.shields.io/github/v/release/SeanDictionary/sage-lsp) ![Platform](https://img.shields.io/badge/platform-Linux-green) ![License](https://img.shields.io/github/license/SeanDictionary/sage-lsp) ![GitHub repo size](https://img.shields.io/github/repo-size/SeanDictionary/sage-lsp) ![GitHub last commit](https://img.shields.io/github/last-commit/SeanDictionary/sage-lsp) [![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/downloads/) [![SageMath](https://img.shields.io/badge/SageMath-Suggested%2010.9%2B-yellow)](https://www.sagemath.org/) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/sage-lsp?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=GREEN&left_text=Downloads)](https://pepy.tech/projects/sage-lsp)

SageMath Language Server Protocol

> [!TIP]
>This project may work well with SageMath 10.9+. Other versions lack stubs for Cython files, so they may have limited functionality.
>
>However, until now (2026-5-22), SageMath 10.9 is not accessible from conda-forge (but it released on github).
>
>You may need to [install it from source code](https://doc.sagemath.org/html/en/installation/source.html). And edit some code.
>```bash
>git clone --branch 10.9 --single-branch https://github.com/sagemath/sage.git
>cd sage
>mamba env create --file environment-3.13-linux.yml --name sage10.9
>mamba activate sage10.9
>pip install .
>```
>Using `sage --version` to check if successfully installed.

## Features

Supported from plugins(very thanks to those projects, they finished a lot of work):

- [pygls](https://github.com/openlawlibrary/pygls) basic LSP server framework
- [pycodestyle](https://github.com/PyCQA/pycodestyle) linter for style checking
- [autopep8](https://github.com/hhatto/autopep8) formatter for code formatting
- [pyflakes](https://github.com/PyCQA/pyflakes) linter for error checking
- [jedi](https://github.com/davidhalter/jedi) definition, type definiton, hover, references provider
- [parso](https://github.com/davidhalter/parso)(dependency of jedi) for folding
- [docstring-to-markdown](https://github.com/python-lsp/docstring-to-markdown) praser for converting docstrings to markdown for hover information


Supported from native code:

- Support Jupyter notebook
- Only support using `from sage.xxx import xxx` or `import sage.xxx` (no alias)
- Local symbols cache for Sage
- Custom formatting rules for Sage
- Custom error checking for Sage
- Custom definition for Sage symbols
- Custom hover information for Sage symbols
- Check references for Sage (only in current file)
- Jump to definiton in Cython files (`.pyx`) from Stubs (`.pyi`) in Sage 10.8+
- Support type inference for Sage (depend on `.pyi` in Sage 10.8+)
- Support type hints hover info for unfollowed variables
- Quick fix for undefined name in Sage
- Completion for Sage (depend on `.pyi` in Sage 10.8+)

## Install

From source code:
```bash
git clone https://github.com/SeanDictionary/sage-lsp && cd sage-lsp
pip install .
```

From pip:
```bash
pip install sage-lsp
```

## Usage

### Directly run the server

```bash
sagelsp --help  // print usage information
sagelsp --sage  // print if SageMath is available and its version
sagelsp -l      // set log level (default: INFO)
sagelsp --clear // clear local symbols cache and exit
```

### Configuration

The server reads style-related configuration from:

1. Global config: `~/.config/pycodestyle`
2. Project config in workspace root: `.pycodestyle`, `setup.cfg`, `tox.ini`

Project config overrides global config.

For project config files, only the first file found in this order is used:

1. `.pycodestyle`
2. `setup.cfg`
3. `tox.ini`

The parser currently reads these sections:

- `[pycodestyle]`
- `[autopep8]`
- `[notebook]`

Top 2 sections are 

#### `[pycodestyle]`

Used for style diagnostics from `pycodestyle`.

Supported keys:

- `select`
- `ignore`
- `exclude`
- `max-line-length`
- `indent-size`
- `hang-closing`
- `experimental`
- `aggressive`

Example:

```ini
[pycodestyle]
ignore = E741, E742, E743, E722, E501
max-line-length = 160
```

#### `[autopep8]`

Used for formatting from `autopep8`.

Supported keys:

- `select`
- `ignore`
- `exclude`
- `max-line-length`
- `indent-size`
- `hang-closing`
- `experimental`
- `aggressive`

**If `[autopep8]` is missing, the server falls back to `[pycodestyle]` for formatter config.**

Example:

```ini
[autopep8]
max-line-length = 100
aggressive = 1
```

#### `[notebook]`

Used for Jupyter notebook cell-specific overrides.

At the moment, this section supports:

- `ignore`

Its values are appended to the normal config when formatting or linting notebook cells.This is useful for rules that are often noisy in cells, such as trailing blank lines at the end of a cell.

Example: Usually, checking W391 (blank line at end of file) and W292 (no newline at end of file) is useless in notebook cells

```ini
[notebook]
ignore = W391, W292
```

#### Complete example

All sections can be empty.

```ini
[pycodestyle]
ignore = E741, E742, E743, E722, E501
max-line-length = 160

[autopep8]
max-line-length = 120
aggressive = 1

[notebook]
ignore = W391, W292
```

### Using with extension [SageMath-for-VScode](https://github.com/SeanDictionary/SageMath-for-VScode)

>[!TIP]
>Make sure you have installed the package `sage-lsp` in the same Python environment as your SageMath installation, and that the extension can import it.

Install pre-release version **2.0.2-beta** from Extension Market to try the new features.

The sorce code of the extension is in [SeanDictionary/SageMath-for-VScode](https://github.com/SeanDictionary/SageMath-for-VScode/tree/v2.0.2-beta). You can also download the pre-release version from [GitHub Releases](https://github.com/SeanDictionary/SageMath-for-VScode/releases/tag/v2.0.2-beta)

## Change Logs

See [CHANGELOG.md](./CHANGELOG.md)

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md)

## License

This project is licensed under the GPL-3.0 License. See the [LICENSE](./LICENSE) file for details.
