turbo-editors/turbo-python · enable-completion.md

turbo-editors/turbo-pythonpublic⑂ Fork 0

⑂ main

enable-completion.md · 95 lines · 4.6 KBmarkdown    Blame HistoryRaw
📦 Turbo Python   1# How to enable Python completion
3This guide shows how to get completion, hovers and go-to-definition working. It assumes Turbo Python is already installed and that you know what a Python project is.
5Completion comes from **pylsp**, the official Python language server. Turbo Python does not bundle it: editing and colouring work without it, and only completion is lost.
7## 1. Install pylsp
10pipx component add pylsp
13## 2. Make sure Turbo Python can find it
15Turbo Python looks on `PATH` first, then in `$GOBIN`, then in `$GOPATH/bin`. `go install` writes to the last of those, which is very often not on `PATH` — so this usually works without any further step. Check:
18pylsp version
21If that says "command not found" but Turbo Python still finds it, that is expected and fine.
23## 3. Open a file inside a module
26cd /path/to/your/module   # the directory holding pyproject.toml
27turbo-python main.py
30Turbo Python walks up from the file looking for `pyproject.toml` and starts pylsp in the directory it finds. **Outside a module, pylsp has very little to say** — this is the most common reason completion appears not to work.
32## 4. Ask for a completion
34Put the cursor after a dot and press **Ctrl-Space**:
40A list drops down under the cursor. Keep typing to narrow it, **↑ ↓** to walk it, **Enter** or **Tab** to accept, **Escape** to dismiss.
42Typing a `.` asks for a completion by itself, so most of the time you do not press anything.
44## Checking what the server is doing
46The right-hand end of the status bar shows the language server's state: `LSP: starting…`, `LSP: ready`, or why there is none. `Run ▸ Language server status` shows the same thing in a box.
48## Variants
50**You do not want a language server at all:**
53turbo-python -no-lsp main.py
56**Completion is dead in a window that started without a name.** An Untitled window has no file to announce to pylsp until it is saved — press **F2** and give it a name ending in `.py`, somewhere under the project. From that save on, completion, hover and the error marks work in that window; there is no need to quit and relaunch.
58**Completion is empty in a file that does compile.** pylsp needs the file's package to build. Check `uv sync` first — a package that does not compile often yields nothing useful.
60**The first completion after opening a large module is slow.** pylsp is loading the module graph. The status bar says `LSP: starting…` until it is ready; requests made before then are refused rather than queued.
62**A request takes too long.** Every request gives up after three seconds, so a stuck server slows the editor but never freezes it. The status bar reports the failure.
64**The list is empty in a file that does not compile.** pylsp answers *nothing at all* — no error, an empty list — for a package it cannot load. A duplicate declaration or an unresolved import is enough. The editor now says which problem is in the way:
67No completions — this file does not compile: main redeclared in this block
70`Run ▸ Language server status` shows the same thing with the server's path, the workspace root, and whether it has been told about this file. Fix the package first — `uv sync` is the quickest check.
72**Ctrl-Space does nothing.** tmux, screen and IDE terminals frequently claim `Ctrl-Space` before the editor sees it. Type a `.` instead, which asks for a completion by itself, or use `Run ▸ Completion`.
74## What else the server gives you
76Completion is the loudest thing it does and the least of what it knows. The same connection answers eight more questions, all of them in the **Code** menu and all of them about the symbol under the cursor — no selection needed.
78| Key | What it does |
79| --- | --- |
80| **Ctrl-Space** | Completion list |
81| **F1** | Describe the symbol under the cursor |
82| **F12** | Jump to where it is declared |
83| **Shift-F12** | List everywhere it is used |
84| **Ctrl-T** | Find a symbol by name anywhere in the project |
86And, without a key: *Go to type definition*, *Find implementations…*, *Symbol in file…* and *Problems…*.
88Problems it finds arrive unasked. The first error in the file you are editing appears on the right of the status bar, prefixed with `⚠`; every line with a problem gets a mark in the gutter (`×` for an error, `!` for a warning); and **Code ▸ Problems…** lists all of them, for every file the server has loaded.
90[How to ask what the code means](ask-about-code.md) walks through all of it.
92## See also
94- Why the server is optional: [Colouring and completion](../explanation/colouring-and-completion.md)
95- Every key: [keyboard reference](../reference/keyboard.md)

📦 Turbo Python 6fc62ea k33g 10h ago	1	# How to enable Python completion
	2
	3	This guide shows how to get completion, hovers and go-to-definition working. It assumes Turbo Python is already installed and that you know what a Python project is.
	4
	5	Completion comes from pylsp, the official Python language server. Turbo Python does not bundle it: editing and colouring work without it, and only completion is lost.
	6
	7	## 1. Install pylsp
	8
	9	```bash
	10	pipx component add pylsp
	11	```
	12
	13	## 2. Make sure Turbo Python can find it
	14
	15	Turbo Python looks on `PATH` first, then in `$GOBIN`, then in `$GOPATH/bin`. `go install` writes to the last of those, which is very often not on `PATH` — so this usually works without any further step. Check:
	16
	17	```bash
	18	pylsp version
	19	```
	20
	21	If that says "command not found" but Turbo Python still finds it, that is expected and fine.
	22
	23	## 3. Open a file inside a module
	24
	25	```bash
	26	cd /path/to/your/module # the directory holding pyproject.toml
	27	turbo-python main.py
	28	```
	29
	30	Turbo Python walks up from the file looking for `pyproject.toml` and starts pylsp in the directory it finds. Outside a module, pylsp has very little to say — this is the most common reason completion appears not to work.
	31
	32	## 4. Ask for a completion
	33
	34	Put the cursor after a dot and press Ctrl-Space:
	35
	36	```go
	37	fmt.
	38	```
	39
	40	A list drops down under the cursor. Keep typing to narrow it, ↑ ↓ to walk it, Enter or Tab to accept, Escape to dismiss.
	41
	42	Typing a `.` asks for a completion by itself, so most of the time you do not press anything.
	43
	44	## Checking what the server is doing
	45
	46	The right-hand end of the status bar shows the language server's state: `LSP: starting…`, `LSP: ready`, or why there is none. `Run ▸ Language server status` shows the same thing in a box.
	47
	48	## Variants
	49
	50	You do not want a language server at all:
	51
	52	```bash
	53	turbo-python -no-lsp main.py
	54	```
	55
	56	Completion is dead in a window that started without a name. An Untitled window has no file to announce to pylsp until it is saved — press F2 and give it a name ending in `.py`, somewhere under the project. From that save on, completion, hover and the error marks work in that window; there is no need to quit and relaunch.
	57
	58	Completion is empty in a file that does compile. pylsp needs the file's package to build. Check `uv sync` first — a package that does not compile often yields nothing useful.
	59
	60	The first completion after opening a large module is slow. pylsp is loading the module graph. The status bar says `LSP: starting…` until it is ready; requests made before then are refused rather than queued.
	61
	62	A request takes too long. Every request gives up after three seconds, so a stuck server slows the editor but never freezes it. The status bar reports the failure.
	63
	64	The list is empty in a file that does not compile. pylsp answers nothing at all — no error, an empty list — for a package it cannot load. A duplicate declaration or an unresolved import is enough. The editor now says which problem is in the way:
65
66	```
67	No completions — this file does not compile: main redeclared in this block
68	```
69
70	`Run ▸ Language server status` shows the same thing with the server's path, the workspace root, and whether it has been told about this file. Fix the package first — `uv sync` is the quickest check.
71
72	Ctrl-Space does nothing. tmux, screen and IDE terminals frequently claim `Ctrl-Space` before the editor sees it. Type a `.` instead, which asks for a completion by itself, or use `Run ▸ Completion`.
73
74	## What else the server gives you
75
76	Completion is the loudest thing it does and the least of what it knows. The same connection answers eight more questions, all of them in the Code menu and all of them about the symbol under the cursor — no selection needed.
77
78	\| Key \| What it does \|
79	\| --- \| --- \|
80	\| Ctrl-Space \| Completion list \|
81	\| F1 \| Describe the symbol under the cursor \|
82	\| F12 \| Jump to where it is declared \|
83	\| Shift-F12 \| List everywhere it is used \|
84	\| Ctrl-T \| Find a symbol by name anywhere in the project \|
85
86	And, without a key: Go to type definition, Find implementations…, Symbol in file… and Problems….
87
88	Problems it finds arrive unasked. The first error in the file you are editing appears on the right of the status bar, prefixed with `⚠`; every line with a problem gets a mark in the gutter (`×` for an error, `!` for a warning); and Code ▸ Problems… lists all of them, for every file the server has loaded.
89
90	[How to ask what the code means](ask-about-code.md) walks through all of it.
91
92	## See also
93
94	- Why the server is optional: [Colouring and completion](../explanation/colouring-and-completion.md)
95	- Every key: [keyboard reference](../reference/keyboard.md)