Tutorial: your first file in Turbo Python

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216

# Tutorial: your first file in Turbo Python

By the end of this tutorial, you will have built the editor, written a small Python program inside it, watched the keywords turn colour as you typed, saved the file, and run it. It takes about ten minutes.

No prior knowledge of Turbo Python is needed. You need Go 1.26 or later to build the editor, and [uv](https://docs.astral.sh/uv/) to make and run the Python project.

## Prerequisites

Check that Go is there — the editor is written in Go, even though it is an editor for Python:

```bash
go version
```

You should see something like:

```
go version go1.26.5 linux/arm64
```

If that command fails, install Go first: https://go.dev/dl/

Check that uv is there too:

```bash
uv --version
```

You should see something like:

```
uv 0.9.26
```

If that command fails, install uv first: https://docs.astral.sh/uv/getting-started/installation/

## Step 1 — Build the editor

From the project directory, type:

```bash
make build
```

You should see a `go build` line, then a line naming the version the binary reports. That last line is a check, not decoration: it runs the binary you just linked and refuses a build whose version stamp never reached it.

We now have an executable at `bin/turbo-python`. Remember where it is, so we can start it from anywhere:

```bash
export TURBO="$PWD/bin/turbo-python"
```

## Step 2 — Create a place to work

Turbo Python is at its best inside a project, so let us make one:

```bash
cd /tmp && uv init hello && cd hello
```

You should see:

```
Initialized project `hello` at `/tmp/hello`
```

`uv init` writes a `pyproject.toml`, a `README.md`, a `.python-version` and a `main.py` with a hello-world in it. `pyproject.toml` is what Turbo Python looks for to find the root of a project, and it is where `pylsp` will be started. We are going to replace `main.py`'s contents with our own.

## Step 3 — Open the editor

Start Turbo Python on the file uv made:

```bash
$TURBO main.py
```

The screen fills with a blue desktop. You should see:

- a **menu bar** across the top: `File  Edit  Search  Run  Code  Options  Window  Snippets  Python  Help`
- a **window** framed in a double line, titled `main.py`
- a **status bar** along the bottom: `F1 Describe  F2 Save  F3 Open …`

The cursor is blinking at line 1, column 1 — the status bar says `1:1` on the right.

Beside it, the status bar says one of two things. `LSP: ready` means the language server was found and started. `LSP: no pylsp — pipx install "python-lsp-server[all]"` means it was not, and names the one command that installs it. Either way the rest of this tutorial works; the [completion guide](../how-to/enable-completion.md) is where to go if you want the second to become the first.

We are inside the editor.

## Step 4 — Clear the file and type a Python program

Press **Ctrl-A** to select everything uv wrote, then **Delete** to remove it. The window is now empty and its title reads `main.py *` — the star means there are unsaved changes.

Type this line and press **Enter**:

```python
def greet(name):
```

Watch the colours as you type. `def` turns **white and bold** the moment the word ends: it is a keyword. `greet` turns **yellow and bold** as soon as you type the `(` after it, because that makes it a function. `name` stays plain **yellow**: it is an ordinary identifier.

(Those are Turbo Classic's colours, the ones the editor starts in. Step 8 changes them.)

Now type four spaces yourself, and then the next line:

```python
    message = f"Hello from {name}!"
```

**Enter copies the current line's indentation; it does not add a level after a colon.** Python's blocks are made of indentation, and where a new one starts is not something the editor tries to guess — so the four spaces are yours to type once, and every line after this one keeps them for free.

`f"Hello from {name}!"` turns **green**, all of it, including the `{name}` in the middle. It is one string: what is inside the braces is Python, but it is not coloured as Python, because deciding where an expression ends inside a literal needs a parser and this is a scanner. That trade-off is written down in [Colouring and completion](../explanation/colouring-and-completion.md).

Press **Enter** — the cursor lands under the `m`, already indented — and type:

```python
    print(message)
```

`print` turns **aqua and bold**: it is one of the builtins the language provides rather than a name from your code.

Press **Enter**, then **Shift-Tab** to take the indent back off, and type the last line:

```python
greet("Turbo Python")
```

We have just written a complete Python program, with the editor colouring it as we went.

If the status bar said `LSP: ready` earlier, look at the left edge of the last line: there is a `!` in the gutter. The language server has an opinion about our file, and **Code ▸ Problems…** says what it is — `warning  main.py:4  E305 expected 2 blank lines after class or function definition`. It is a style rule rather than an error, and leaving it is fine; the point is that the mark and the message are there, and they arrive without anybody asking.

## Step 5 — Save it

Press **F2**.

The star disappears from the title, and the status bar shows, for a moment:

```
Saved main.py
```

It goes back to the key hints after that — the message is a confirmation, not a state. The title without its star is the state.

## Step 6 — Look at the file from outside

Leave the editor by pressing **Alt-X**. The terminal comes back as it was.

Check what we wrote:

```bash
cat main.py
```

You should see:

```python
def greet(name):
    message = f"Hello from {name}!"
    print(message)
greet("Turbo Python")
```

## Step 7 — Run it

```bash
uv run main.py
```

The first run makes the environment, so you should see a line or two from uv before the output:

```
Using CPython 3.14.4 interpreter at: /usr/bin/python3.14
Creating virtual environment at: .venv
Hello from Turbo Python!
```

That is a working Python program, written entirely inside the editor.

## Step 8 — Change the theme

Open the file again:

```bash
$TURBO main.py
```

Press **F10**. The `File` menu drops open. Press **→** five times: the menu walks along the bar to `Options`, whose first item, `Theme…`, is highlighted. Press **Enter**.

A list of eleven appears, in alphabetical order, with the theme you are using already highlighted:

```
borland-light
cappuccino
catppuccin-frappe
catppuccin-latte
cobalt
darcula
intellij-light
monochrome-dark
monochrome-light
turbo-classic
turbo-dark
```

`turbo-classic` is the highlighted row, because that is the theme you are in. Press **↓** once to move to `turbo-dark`, then press **Enter**.

The whole editor repaints in dark grey, and the status bar says `Theme: Turbo Dark`.

Press **Alt-X** to leave.

## What now?

You have built the editor, written a Python program in it, saved it, run it, and changed how it looks.

- To do specific things — enable completion, write a theme of your own, search a file → see the [how-to guides](../how-to/)
- To look up a key or a menu item → see the [reference](../reference/)
- To understand how the colouring and the completion actually work → see the [explanation](../explanation/)