turbo-editors/turbo-python · architecture.md

turbo-editors/turbo-pythonpublic⑂ Fork 0

⑂ v1.0.0

architecture.md · 97 lines · 7.4 KBmarkdown    Blame HistoryRaw
📦 Turbo Python   1# Architecture — explanation
3## What is this about?
5Turbo Python is a command, a profile and a scanner. Everything else — the editing widget, the windows, the menus, the dialogs, the themes, the terminal emulator, the file tree, the LSP client — is [turbo-core](https://rickub.com/turbo-editors/turbo-core), the library every Turbo editor is built on.
7This page is about that split: what is here, what is there, and why the line falls where it does.
9## What is in this repository
12main.go                  flags, the terminal, and the wiring
13internal/pythonlang      the whole of what makes this Turbo Python
14  pythonlang.go          the profile: name, menu, server, root markers, where pylsp hides
15  scan.go                the scanner's dispatcher, comments, decorators
16  literals.go            the sixteen spellings of a string literal
17  words.go               numbers, keywords, builtins, the naming conventions
18  templates.go           three //go:embed declarations
19  *.toml.tmpl            the three starter files a project gets, embedded
22About eight hundred lines, of which six hundred are the scanner. There is no `internal/app`, no `internal/ui`, no `internal/buffer` — those exist once, in the library, and all six editors use them unchanged.
24## What `main` does
26Six things, in this order:
281. Parses the flags.
292. Calls `pythonlang.Register()`, which teaches the library to colour `.py` files.
303. Builds `pythonlang.Profile()` — the value that says this editor is Turbo Python.
314. Reads `.turbo-python/settings.toml` from the working directory, if there is one.
325. Opens the terminal and hands the screen, the theme name and the profile to `app.New`.
336. Starts pylsp in the project root, and runs the event loop.
35That is the whole command. Every decision it makes — which theme wins, which files to open, whether to start a language server — is about *this run*, not about Python.
37## The profile is the seam
40profile.Profile{
41	Name:        "Turbo Python",
42	Slug:        "turbo-python",
43	Language:    "Python",
44	ToolsMenu:   "~P~ython",
45	RootMarkers: []string{"pyproject.toml", "setup.py", "setup.cfg"},
46	Server:      profile.Server{Command: "pylsp", …},
47	Templates:   profile.Templates{Settings: …, Snippets: …, Tools: …},
51Everything that would otherwise be a hardcoded `"turbo-python"`, `"pylsp"` or `"pyproject.toml"` somewhere in eleven thousand lines is one field here. The library reads them; nothing in the library knows what any of them mean.
53`Slug` carries more than it looks. The binary is `turbo-python`, the project directory is `.turbo-python`, the user's own configuration lives in `~/.config/turbo-python`, and the environment variables that override it are `TURBO_PYTHON_THEME_DIR` and `TURBO_PYTHON_SNIPPET_DIR` — all derived from that one word.
55## Why the scanner is here and not in the library
57turbo-core colours eight languages itself: TOML, YAML, Markdown, JavaScript, HTML, XML, Dockerfiles and shell. Those are the ones every editor meets whatever it is for — a project's configuration is TOML or YAML, its documentation is Markdown, its scripts are shell, its image build a Dockerfile.
59Python is not one of them, and neither are Go and Rust. The language that *defines* an editor is registered by that editor, which is why a `.rs` file opens as plain text here and a `.py` file opens as plain text in Turbo Rust.
61That could have gone the other way. Putting all three scanners in the library would let any editor colour any of the languages, at no cost in dependencies — a Python scanner is ordinary Go. It was rejected because it would mean the library grows a language every time somebody builds an editor, and because "what does this editor register?" would stop being the first question about a new one.
63## Why the toolchain menu is `~P~ython` and not `~U~v`
65The hot key was the easy part. Nine letters are taken by the fixed menus — F, E, S, R, C, O, W, N and H — and `P` is not one of them, so it lands on the first letter of the word, which costs nobody a second glance. Turbo Rust had no such luck and ended up on `Rus~t~`.
67The name was the real decision, and it went the same way Turbo Rust's did. The menu holds whatever the project put in its tools file, and that is not always uv: the first tools file anybody writes outgrows the language's own toolchain, because a project's commands include containers, databases and a `Makefile` target somebody added in 2019. A menu called **uv** holding `docker compose up` is a lie about what the menu is, in exactly the way the library's own documentation warns about. `Python` is the language, and the language is what this editor is for.
69## Why the tests drive the real editor
71`internal/pythonlang/editor_test.go` builds a whole Turbo Python on a simulated terminal — `app.New(screen, "turbo-classic", pythonlang.Profile())` — opens a file and checks the colouring, the menu bar and the hot keys. It uses only the library's public API.
73That is deliberate. The library's own suite proves the library works; what these tests prove is that *this editor is assembled correctly* — that `Register` was called, that the profile reached the menu bar, that a `.py` file comes out coloured. A bug where `main` forgot to register Python would pass every test in turbo-core.
75The same file drives a **real pylsp** end to end, four times over. It writes a project, opens a file, starts the server, and then:
77- **types text that exists only in the buffer** and asks for a completion — text already on disk proves nothing, because the server answers from disk for anything it has not been told is open;
78- asks for the **references** of a name used in three places, which is the answer shape that used to be truncated to one;
79- asks for the **file's symbols**, which is a different answer shape again;
80- opens a file that **does not parse** and waits for a diagnostic to arrive unasked — the one feature whose failure looks exactly like success, because an editor with no error to show and one that cannot find the error are the same blank gutter.
82A fifth test pins what pylsp *cannot* do: it advertises neither `implementation` nor `workspace/symbol`, the documentation says so, and the test fails if a future pylsp starts answering — so the page gets revisited rather than quietly going stale.
84## Rejected alternatives
86**Forking Turbo Rust.** The obvious way to get a third editor, and the reason the library exists instead: three copies of eleven thousand lines drift within a month, and every fix has to be made three times by somebody who remembers there are three.
88**A plugin system.** Turbo Python is a Go program that imports a library. There is no dynamic loading and no ABI. Adding one would mean freezing the API of every package in turbo-core rather than of the handful a profile touches.
90**A configuration file instead of a profile.** The profile could have been TOML read at start-up, which would make a new editor a file rather than a program. It would also make the scanner inexpressible, and a half-configurable editor — everything but the colouring — is worse than either whole answer.
92## How it relates to the rest
94- What each of the library's packages does: [turbo-core's package reference](https://rickub.com/turbo-editors/turbo-core/blob/main/docs/en/reference/packages.md)
95- How the colouring works here: [Colouring and completion](colouring-and-completion.md)
96- Why the tools menu is data: [Python tools](python-tools.md)
97- The decisions that outlived the refactoring: [Design decisions](design-decisions.md)

📦 Turbo Python 6fc62ea k33g 10h ago	1	# Architecture — explanation
	2
	3	## What is this about?
	4
	5	Turbo Python is a command, a profile and a scanner. Everything else — the editing widget, the windows, the menus, the dialogs, the themes, the terminal emulator, the file tree, the LSP client — is [turbo-core](https://rickub.com/turbo-editors/turbo-core), the library every Turbo editor is built on.
	6
	7	This page is about that split: what is here, what is there, and why the line falls where it does.
	8
	9	## What is in this repository
	10
	11	```
	12	main.go flags, the terminal, and the wiring
	13	internal/pythonlang the whole of what makes this Turbo Python
	14	pythonlang.go the profile: name, menu, server, root markers, where pylsp hides
	15	scan.go the scanner's dispatcher, comments, decorators
	16	literals.go the sixteen spellings of a string literal
	17	words.go numbers, keywords, builtins, the naming conventions
	18	templates.go three //go:embed declarations
	19	*.toml.tmpl the three starter files a project gets, embedded
	20	```
	21
	22	About eight hundred lines, of which six hundred are the scanner. There is no `internal/app`, no `internal/ui`, no `internal/buffer` — those exist once, in the library, and all six editors use them unchanged.
	23
	24	## What `main` does
	25
	26	Six things, in this order:
	27
	28	1. Parses the flags.
	29	2. Calls `pythonlang.Register()`, which teaches the library to colour `.py` files.
	30	3. Builds `pythonlang.Profile()` — the value that says this editor is Turbo Python.
	31	4. Reads `.turbo-python/settings.toml` from the working directory, if there is one.
	32	5. Opens the terminal and hands the screen, the theme name and the profile to `app.New`.
	33	6. Starts pylsp in the project root, and runs the event loop.
	34
	35	That is the whole command. Every decision it makes — which theme wins, which files to open, whether to start a language server — is about this run, not about Python.
	36
	37	## The profile is the seam
	38
	39	```go
	40	profile.Profile{
	41	Name: "Turbo Python",
	42	Slug: "turbo-python",
	43	Language: "Python",
	44	ToolsMenu: "~P~ython",
	45	RootMarkers: []string{"pyproject.toml", "setup.py", "setup.cfg"},
	46	Server: profile.Server{Command: "pylsp", …},
	47	Templates: profile.Templates{Settings: …, Snippets: …, Tools: …},
	48	}
	49	```
	50
	51	Everything that would otherwise be a hardcoded `"turbo-python"`, `"pylsp"` or `"pyproject.toml"` somewhere in eleven thousand lines is one field here. The library reads them; nothing in the library knows what any of them mean.
	52
	53	`Slug` carries more than it looks. The binary is `turbo-python`, the project directory is `.turbo-python`, the user's own configuration lives in `~/.config/turbo-python`, and the environment variables that override it are `TURBO_PYTHON_THEME_DIR` and `TURBO_PYTHON_SNIPPET_DIR` — all derived from that one word.
	54
	55	## Why the scanner is here and not in the library
	56
	57	turbo-core colours eight languages itself: TOML, YAML, Markdown, JavaScript, HTML, XML, Dockerfiles and shell. Those are the ones every editor meets whatever it is for — a project's configuration is TOML or YAML, its documentation is Markdown, its scripts are shell, its image build a Dockerfile.
	58
	59	Python is not one of them, and neither are Go and Rust. The language that defines an editor is registered by that editor, which is why a `.rs` file opens as plain text here and a `.py` file opens as plain text in Turbo Rust.
	60
	61	That could have gone the other way. Putting all three scanners in the library would let any editor colour any of the languages, at no cost in dependencies — a Python scanner is ordinary Go. It was rejected because it would mean the library grows a language every time somebody builds an editor, and because "what does this editor register?" would stop being the first question about a new one.
	62
	63	## Why the toolchain menu is `~P~ython` and not `~U~v`
	64
65	The hot key was the easy part. Nine letters are taken by the fixed menus — F, E, S, R, C, O, W, N and H — and `P` is not one of them, so it lands on the first letter of the word, which costs nobody a second glance. Turbo Rust had no such luck and ended up on `Rus~t~`.
66
67	The name was the real decision, and it went the same way Turbo Rust's did. The menu holds whatever the project put in its tools file, and that is not always uv: the first tools file anybody writes outgrows the language's own toolchain, because a project's commands include containers, databases and a `Makefile` target somebody added in 2019. A menu called uv holding `docker compose up` is a lie about what the menu is, in exactly the way the library's own documentation warns about. `Python` is the language, and the language is what this editor is for.
68
69	## Why the tests drive the real editor
70
71	`internal/pythonlang/editor_test.go` builds a whole Turbo Python on a simulated terminal — `app.New(screen, "turbo-classic", pythonlang.Profile())` — opens a file and checks the colouring, the menu bar and the hot keys. It uses only the library's public API.
72
73	That is deliberate. The library's own suite proves the library works; what these tests prove is that this editor is assembled correctly — that `Register` was called, that the profile reached the menu bar, that a `.py` file comes out coloured. A bug where `main` forgot to register Python would pass every test in turbo-core.
74
75	The same file drives a real pylsp end to end, four times over. It writes a project, opens a file, starts the server, and then:
76
77	- types text that exists only in the buffer and asks for a completion — text already on disk proves nothing, because the server answers from disk for anything it has not been told is open;
78	- asks for the references of a name used in three places, which is the answer shape that used to be truncated to one;
79	- asks for the file's symbols, which is a different answer shape again;
80	- opens a file that does not parse and waits for a diagnostic to arrive unasked — the one feature whose failure looks exactly like success, because an editor with no error to show and one that cannot find the error are the same blank gutter.
81
82	A fifth test pins what pylsp cannot do: it advertises neither `implementation` nor `workspace/symbol`, the documentation says so, and the test fails if a future pylsp starts answering — so the page gets revisited rather than quietly going stale.
83
84	## Rejected alternatives
85
86	Forking Turbo Rust. The obvious way to get a third editor, and the reason the library exists instead: three copies of eleven thousand lines drift within a month, and every fix has to be made three times by somebody who remembers there are three.
87
88	A plugin system. Turbo Python is a Go program that imports a library. There is no dynamic loading and no ABI. Adding one would mean freezing the API of every package in turbo-core rather than of the handful a profile touches.
89
90	A configuration file instead of a profile. The profile could have been TOML read at start-up, which would make a new editor a file rather than a program. It would also make the scanner inexpressible, and a half-configurable editor — everything but the colouring — is worse than either whole answer.
91
92	## How it relates to the rest
93
94	- What each of the library's packages does: [turbo-core's package reference](https://rickub.com/turbo-editors/turbo-core/blob/main/docs/en/reference/packages.md)
95	- How the colouring works here: [Colouring and completion](colouring-and-completion.md)
96	- Why the tools menu is data: [Python tools](python-tools.md)
97	- The decisions that outlived the refactoring: [Design decisions](design-decisions.md)