turbo-editors/turbo-python · getting-started.md

turbo-editors/turbo-pythonpublic⑂ Fork 0

⑂ v1.0.2

getting-started.md · 216 lines · 7.1 KBmarkdown    Blame HistoryRaw
📦 Turbo Python   1# Tutorial: your first file in Turbo Python
3By 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.
5No 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.
7## Prerequisites
9Check that Go is there — the editor is written in Go, even though it is an editor for Python:
12
15You should see something like:
18go version go1.26.5 linux/arm64
21If that command fails, install Go first: https://go.dev/dl/
23Check that uv is there too:
26uv --version
29You should see something like:
32
35If that command fails, install uv first: https://docs.astral.sh/uv/getting-started/installation/
37## Step 1 — Build the editor
39From the project directory, type:
42
45You 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.
47We now have an executable at `bin/turbo-python`. Remember where it is, so we can start it from anywhere:
50export TURBO="$PWD/bin/turbo-python"
53## Step 2 — Create a place to work
55Turbo Python is at its best inside a project, so let us make one:
58cd /tmp && uv init hello && cd hello
61You should see:
64Initialized project `hello` at `/tmp/hello`
67`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.
69## Step 3 — Open the editor
71Start Turbo Python on the file uv made:
74$TURBO main.py
77The screen fills with a blue desktop. You should see:
79- a **menu bar** across the top: `File  Edit  Search  Run  Code  Options  Window  Snippets  Python  Help`
80- a **window** framed in a double line, titled `main.py`
81- a **status bar** along the bottom: `F1 Describe  F2 Save  F3 Open …`
83The cursor is blinking at line 1, column 1 — the status bar says `1:1` on the right.
85Beside 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.
87We are inside the editor.
89## Step 4 — Clear the file and type a Python program
91Press **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.
93Type this line and press **Enter**:
95
96def greet(name):
99Watch 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.
101(Those are Turbo Classic's colours, the ones the editor starts in. Step 8 changes them.)
103Now type four spaces yourself, and then the next line:
105
106    message = f"Hello from {name}!"
109**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.
111`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).
113Press **Enter** — the cursor lands under the `m`, already indented — and type:
115
116    print(message)
119`print` turns **aqua and bold**: it is one of the builtins the language provides rather than a name from your code.
121Press **Enter**, then **Shift-Tab** to take the indent back off, and type the last line:
123
124greet("Turbo Python")
127We have just written a complete Python program, with the editor colouring it as we went.
129If 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.
131## Step 5 — Save it
133Press **F2**.
135The star disappears from the title, and the status bar shows, for a moment:
138Saved main.py
141It goes back to the key hints after that — the message is a confirmation, not a state. The title without its star is the state.
143## Step 6 — Look at the file from outside
145Leave the editor by pressing **Alt-X**. The terminal comes back as it was.
147Check what we wrote:
150cat main.py
153You should see:
155
156def greet(name):
157    message = f"Hello from {name}!"
158    print(message)
159greet("Turbo Python")
162## Step 7 — Run it
165uv run main.py
168The first run makes the environment, so you should see a line or two from uv before the output:
171Using CPython 3.14.4 interpreter at: /usr/bin/python3.14
172Creating virtual environment at: .venv
173Hello from Turbo Python!
176That is a working Python program, written entirely inside the editor.
178## Step 8 — Change the theme
180Open the file again:
183$TURBO main.py
186Press **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**.
188A list of eleven appears, in alphabetical order, with the theme you are using already highlighted:
191borland-light
192
193catppuccin-frappe
194catppuccin-latte
197intellij-light
198monochrome-dark
199monochrome-light
200turbo-classic
201
204`turbo-classic` is the highlighted row, because that is the theme you are in. Press **↓** once to move to `turbo-dark`, then press **Enter**.
206The whole editor repaints in dark grey, and the status bar says `Theme: Turbo Dark`.
208Press **Alt-X** to leave.
210## What now?
212You have built the editor, written a Python program in it, saved it, run it, and changed how it looks.
214- To do specific things — enable completion, write a theme of your own, search a file → see the [how-to guides](../how-to/)
215- To look up a key or a menu item → see the [reference](../reference/)
216- To understand how the colouring and the completion actually work → see the [explanation](../explanation/)

📦 Turbo Python 6fc62ea k33g 10h ago	1	# Tutorial: your first file in Turbo Python
	2
	3	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.
	4
	5	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.
	6
	7	## Prerequisites
	8
	9	Check that Go is there — the editor is written in Go, even though it is an editor for Python:
	10
	11	```bash
	12	go version
	13	```
	14
	15	You should see something like:
	16
	17	```
	18	go version go1.26.5 linux/arm64
	19	```
	20
	21	If that command fails, install Go first: https://go.dev/dl/
	22
	23	Check that uv is there too:
	24
	25	```bash
	26	uv --version
	27	```
	28
	29	You should see something like:
	30
	31	```
	32	uv 0.9.26
	33	```
	34
	35	If that command fails, install uv first: https://docs.astral.sh/uv/getting-started/installation/
	36
	37	## Step 1 — Build the editor
	38
	39	From the project directory, type:
	40
	41	```bash
	42	make build
	43	```
	44
	45	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.
	46
	47	We now have an executable at `bin/turbo-python`. Remember where it is, so we can start it from anywhere:
	48
	49	```bash
	50	export TURBO="$PWD/bin/turbo-python"
	51	```
	52
	53	## Step 2 — Create a place to work
	54
	55	Turbo Python is at its best inside a project, so let us make one:
	56
	57	```bash
	58	cd /tmp && uv init hello && cd hello
	59	```
	60
	61	You should see:
	62
	63	```
	64	Initialized project `hello` at `/tmp/hello`
65	```
66
67	`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.
68
69	## Step 3 — Open the editor
70
71	Start Turbo Python on the file uv made:
72
73	```bash
74	$TURBO main.py
75	```
76
77	The screen fills with a blue desktop. You should see:
78
79	- a menu bar across the top: `File Edit Search Run Code Options Window Snippets Python Help`
80	- a window framed in a double line, titled `main.py`
81	- a status bar along the bottom: `F1 Describe F2 Save F3 Open …`
82
83	The cursor is blinking at line 1, column 1 — the status bar says `1:1` on the right.
84
85	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.
86
87	We are inside the editor.
88
89	## Step 4 — Clear the file and type a Python program
90
91	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.
92
93	Type this line and press Enter:
94
95	```python
96	def greet(name):
97	```
98
99	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.
100
101	(Those are Turbo Classic's colours, the ones the editor starts in. Step 8 changes them.)
102
103	Now type four spaces yourself, and then the next line:
104
105	```python
106	message = f"Hello from {name}!"
107	```
108
109	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.
110
111	`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).
112
113	Press Enter — the cursor lands under the `m`, already indented — and type:
114
115	```python
116	print(message)
117	```
118
119	`print` turns aqua and bold: it is one of the builtins the language provides rather than a name from your code.
120
121	Press Enter, then Shift-Tab to take the indent back off, and type the last line:
122
123	```python
124	greet("Turbo Python")
125	```
126
127	We have just written a complete Python program, with the editor colouring it as we went.
128
129	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.
130
131	## Step 5 — Save it
132
133	Press F2.
134
135	The star disappears from the title, and the status bar shows, for a moment:
136
137	```
138	Saved main.py
139	```
140
141	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.
142
143	## Step 6 — Look at the file from outside
144
145	Leave the editor by pressing Alt-X. The terminal comes back as it was.
146
147	Check what we wrote:
148
149	```bash
150	cat main.py
151	```
152
153	You should see:
154
155	```python
156	def greet(name):
157	message = f"Hello from {name}!"
158	print(message)
159	greet("Turbo Python")
160	```
161
162	## Step 7 — Run it
163
164	```bash
165	uv run main.py
166	```
167
168	The first run makes the environment, so you should see a line or two from uv before the output:
169
170	```
171	Using CPython 3.14.4 interpreter at: /usr/bin/python3.14
172	Creating virtual environment at: .venv
173	Hello from Turbo Python!
174	```
175
176	That is a working Python program, written entirely inside the editor.
177
178	## Step 8 — Change the theme
179
180	Open the file again:
181
182	```bash
183	$TURBO main.py
184	```
185
186	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.
187
188	A list of eleven appears, in alphabetical order, with the theme you are using already highlighted:
189
190	```
191	borland-light
192	cappuccino
193	catppuccin-frappe
194	catppuccin-latte
195	cobalt
196	darcula
197	intellij-light
198	monochrome-dark
199	monochrome-light
200	turbo-classic
201	turbo-dark
202	```
203
204	`turbo-classic` is the highlighted row, because that is the theme you are in. Press ↓ once to move to `turbo-dark`, then press Enter.
205
206	The whole editor repaints in dark grey, and the status bar says `Theme: Turbo Dark`.
207
208	Press Alt-X to leave.
209
210	## What now?
211
212	You have built the editor, written a Python program in it, saved it, run it, and changed how it looks.
213
214	- To do specific things — enable completion, write a theme of your own, search a file → see the [how-to guides](../how-to/)
215	- To look up a key or a menu item → see the [reference](../reference/)
216	- To understand how the colouring and the completion actually work → see the [explanation](../explanation/)