# turbo-python

A Turbo C-style editor for Python, written in Go.

Built on **[turbo-core](https://rickub.com/turbo-editors/turbo-core)**, the library every Turbo editor shares. What is in this repository is the command, the profile that says this editor is for Python, and the Python scanner — about seven hundred lines. Everything else lives in the library.

A full-screen terminal IDE with the Borland furniture — a menu bar with hot keys, movable windows that cast shadows, modal dialogs, a clickable status bar — and the things a Python editor needs today: syntax colouring that carries triple-quoted strings across lines and tells a constant from a class, loadable colour themes, completion and diagnostics from `pylsp`, shell windows, per-project settings, a project tree, snippets, and the uv toolchain a menu away.

```
 File  Edit  Search  Run  Code  Options  Window  Snippets  Python  Help
╔═[x]═════════════════════════════ shapes.py ═══════════════════════════════1═[■]╗
║ 1 """A demo module."""                                                        ▲║
║ 2 from abc import ABC, abstractmethod                                         ▓║
║ 3                                                                             ░║
║ 4                                                                             ░║
║ 5 class Shape(ABC):                                                           ░║
║ 6     @abstractmethod                                                         ░║
║ 7     def area(self) -> float: ...                                            ░║
║ 8                                                                             ░║
║ 9 MAX_SIDES = 0x1f_ff                                                         ▼║
║◄▓░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░►║
╚════════════════════════════════════════════════════════════════════════════════╝
 F1 Describe  F2 Save  F3 Open  F6 Window  F7 Next  F10 Menu       1:1  LSP: ready
```

## Getting started

```bash
make install
```

That builds the editor, puts it where your shell looks for commands, and reports what it found — the Go version it built with, where the binary went, whether that directory is on your `PATH`, and whether `pylsp` is installed. Then, from any Python project:

```bash
turbo-python main.py
```

To build without installing, `make build` leaves the binary in `bin/turbo-python`. From the module proxy instead of a checkout: `go install rickub.com/turbo-editors/turbo-python@latest`.

For completion and diagnostics, install the Python language server as well — the editor works without it, and says so on the status bar:

```bash
pipx install "python-lsp-server[all]"
```

The `[all]` is not optional if you want the gutter to show anything: the linters that produce diagnostics are extras, and without them the server has nothing to report.

The [tutorial](docs/en/tutorials/getting-started.md) walks through a first session in about ten minutes.

## Features

- **Every build knows what it is** — `turbo-python -version` and **Help ▸ About** name the version, the commit and the build date, stamped in by the linker from `git describe` rather than read from a constant somebody forgot to bump
- **Turbo Vision interface** — menu bar with `Alt`-letter hot keys, overlapping movable and resizable windows, modal dialogs, mouse support throughout
- **Syntax colouring for nine languages** — Python by a hand-written scanner that carries triple-quoted strings and line continuations exactly, knows all six string prefixes, and separates `SCREAMING_SNAKE_CASE` constants from `CapWords` classes; plus TOML, YAML, Markdown, JavaScript, HTML, XML, Dockerfiles and shell scripts from turbo-core
- **Themes** in TOML, eleven embedded — Borland navy, dark grey, paper white, espresso, Catppuccin Frappé and Latte, cobalt, Darcula and IntelliJ Light, and a hueless monochrome in both polarities — and any number of your own, with inheritance between files and between style keys. Every shipped theme is held to its contrast by tests
- **Per-project settings** in `.turbo-python/settings.toml` — pin a theme, turn on automatic saving — created from a menu item, never by itself, and re-read on every save so a change takes effect without a restart
- **Completion, hover, go-to-definition, references and diagnostics** from `pylsp`, entirely optional. The server is looked for in the active virtual environment, `~/.local/bin`, pyenv's shims and macOS' per-version script directories as well as on `PATH`
- **Terminal windows** — `F8` opens a real shell in a window, with its own VT/ANSI emulator, scrollback and job control (Linux, macOS and Windows)
- **Project tree** — `F9` shows the project's files in a window; walk it with the arrows and press Enter to open one
- **Snippets** — a `Snippets` menu built from `.turbo-python/snippets.toml`, grouped into submenus and filtered by the file you are in; the chosen text is inserted at the cursor, re-indented to match — which in Python is a correctness matter and not a nicety
- **The uv toolchain a menu away** — `Alt-P` runs `uv venv`, `uv sync`, `ruff format`, `ruff check`, `pytest` and your script from `.turbo-python/tools.toml`, each showing its output where the tool asked: a popup that fills in as it goes, a terminal window, or an editing window to search. Files the command rewrote are re-read for you, and a tool naming a `menu` of its own gets that menu on the bar
- **Editing** with word movement, block indent, a shared clipboard, and undo that merges a run of typing into one step
- **Faithful files** — line endings and the trailing newline are preserved, and saving is atomic
- **Automatic saving**, off by default, writing a short while after you stop typing

## Commands

| Command | What it does |
| --- | --- |
| `make install` | Build and install onto your `PATH` |
| `make build` | Compile into `bin/turbo-python` |
| `make test` | Run the whole test suite |
| `make check` | `fmt`, `vet`, then the tests — what a commit should pass |
| `make run FILE=x.py` | Build and start the editor on a file |
| `make help` | List every target |

```bash
turbo-python [-theme name] [-no-lsp] [file...]
turbo-python -list-themes
```

## Documentation

Full documentation in **[English](docs/en/)** and **[French](docs/fr/)**, organised by the [Diátaxis](https://diataxis.fr) method:

| | |
| --- | --- |
| **Tutorial** | [Your first file in Turbo Python](docs/en/tutorials/getting-started.md) |
| **How-to** | [install](docs/en/how-to/install.md) · [run the tests](docs/en/how-to/run-the-tests.md) · [enable completion](docs/en/how-to/enable-completion.md) · [write a theme](docs/en/how-to/write-a-theme.md) · [move around a file](docs/en/how-to/navigate-code.md) · [ask about code](docs/en/how-to/ask-about-code.md) · [use a terminal](docs/en/how-to/use-a-terminal.md) · [configure a project](docs/en/how-to/configure-a-project.md) · [browse a project](docs/en/how-to/browse-a-project.md) · [use snippets](docs/en/how-to/use-snippets.md) · [run uv commands](docs/en/how-to/run-uv-commands.md) · [make a release](docs/en/how-to/make-a-release.md) |
| **Reference** | [command line](docs/en/reference/cli.md) · [keyboard](docs/en/reference/keyboard.md) · [menus](docs/en/reference/menus.md) · [theme format](docs/en/reference/themes.md) · [terminal windows](docs/en/reference/terminal.md) · [project settings](docs/en/reference/project-settings.md) · [project tree](docs/en/reference/project-tree.md) · [languages](docs/en/reference/languages.md) · [snippets](docs/en/reference/snippets.md) · [Python tools](docs/en/reference/python-tools.md) · [the version number](docs/en/reference/versioning.md) |
| **Explanation** | [architecture](docs/en/explanation/architecture.md) · [design decisions](docs/en/explanation/design-decisions.md) · [colouring and completion](docs/en/explanation/colouring-and-completion.md) · [terminal windows](docs/en/explanation/terminal-windows.md) · [project settings](docs/en/explanation/project-settings.md) · [project tree](docs/en/explanation/project-tree.md) · [snippets](docs/en/explanation/snippets.md) · [Python tools](docs/en/explanation/python-tools.md) |

The library's packages each carry their own `README.md` beside the code, in [turbo-core](https://rickub.com/turbo-editors/turbo-core).

## Where the code is

| | |
| --- | --- |
| `main.go` | flags, the terminal, the wiring |
| `internal/pythonlang` | the profile, the Python scanner, the three starter files |
| everything else | [turbo-core](https://rickub.com/turbo-editors/turbo-core) |

The dependency graph is drawn in [`docs/diagrams/packages.drawio`](docs/diagrams/packages.drawio), checked against `go list` by `diagram_test.go`.

## Design in one line

Two dependencies — `tcell/v2` and `BurntSushi/toml` — and everything else from the standard library, including the scanner toolkit and the Language Server Protocol client. Both come through turbo-core; this repository adds none of its own. The [design decisions](docs/en/explanation/design-decisions.md) page explains why.

## Requirements

Go 1.26 or later to build it — the editor is written in Go even though it is an editor for Python. A terminal with mouse reporting, which is all of them. `pylsp` is optional.

## Licence

See [LICENSE](LICENSE).