Metadata-Version: 2.5
Name: thonny-pseudocode-i18n
Version: 0.9.6
Summary: Thonny 5 integration for multilingual pseudocode-i18n via pseudo-lsp
Project-URL: Homepage, https://rod2ik.gitlab.io/thonny-pseudocode-i18n/
Project-URL: Documentation, https://rod2ik.gitlab.io/thonny-pseudocode-i18n/
Project-URL: Repository, https://gitlab.com/rod2ik/thonny-pseudocode-i18n
Project-URL: Issues, https://gitlab.com/rod2ik/thonny-pseudocode-i18n/-/issues
Author: Rod2ik
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: education,i18n,language-server,lsp,pseudocode,thonny
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.11
Requires-Dist: pseudocode-i18n-languageserver<0.10,>=0.9.6
Requires-Dist: pseudocode-i18n<0.10,>=0.9.6
Requires-Dist: pygments-lexer-pseudocode-i18n<0.10,>=0.9.6
Requires-Dist: thonny<6,>=5.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mkdocs-material>=9.6; extra == 'dev'
Requires-Dist: mkdocs<2,>=1.6; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.12; extra == 'dev'
Description-Content-Type: text/markdown

# Pseudocode-i18n for Thonny

| Resource | Link |
| --- | --- |
| Repository | <https://gitlab.com/rod2ik/thonny-pseudocode-i18n> |
| Documentation | <https://rod2ik.gitlab.io/thonny-pseudocode-i18n/> |
| Core language | <https://gitlab.com/rod2ik/pseudocode-i18n> |
| Language server | <https://gitlab.com/rod2ik/pseudocode-i18n-languageserver> |
| Pygments lexer | <https://gitlab.com/rod2ik/pygments-lexer-pseudocode-i18n> |
| MkDocs plugin | <https://gitlab.com/rod2ik/mkdocs-pseudocode-i18n> |
| VS Code extension | <https://gitlab.com/rod2ik/vscode-pseudocode-i18n> |

**Use multilingual `.pseudo` and `.algo` files in Thonny 5 with the same parser, diagnostics, completions, i18n snippets and navigation as the rest of the pseudocode-i18n ecosystem.**

**Current version: 0.9.6.**
**Release history:** [thonny-pseudocode-i18n changelog](https://rod2ik.gitlab.io/thonny-pseudocode-i18n/reference/changelog/).
## Current Thonny experience

The plugin behaves like a native pedagogical Thonny frontend while keeping language intelligence and execution semantics shared:

- syntax coloring uses **Thonny's native Python semantic tags**. No Pseudocode Light/Dark palette is imposed: `Default Light`, `Default Dark`, Zenburn and other themes decide colors from Python-equivalent roles;
- function/class declarations receive `definition + function_definition` / `definition + class_definition`; localized constructors are function definitions; `self` / `this` remain visually ordinary like Python `self`;
- live diagnostics use a **300 ms debounce** and underline error/warning/information ranges with red/orange/blue severity accents adapted to light/dark backgrounds; the Diagnostics tab uses the same red/orange/blue severity colours, refreshes without stealing focus, and exposes each `Lxx` marker as a link back to the exact editor line/column;
- the docked view is visible by default and ordered **Diagnostics → Exécution pas à pas → Documentation → Algorigramme → Informations** (localized from the IDE UI language); when a `.pseudo` / `.algo` file becomes active, **Diagnostics is selected automatically once for that editor activation**, while later refreshes do not steal a deliberately selected tab; all five tabs are disabled whenever the active editor is not a `.pseudo` / `.algo` document, and are re-enabled immediately when a Pseudocode tab becomes active;
- **Exécution pas à pas** consumes the shared `pseudocode-tutor/v1` model from the LSP/core and presents current source line, first/previous/play/pause/next/last controls, variables with old → new changes, call stack, output/input state and a synchronized algorigram; no execution engine is duplicated in the plugin;
- Tutor and flowchart requests carry the active document URI explicitly (`textDocument.uri` plus a compatibility top-level `uri`), while the LSP normalizes the request through one shared parser;
- Thonny’s native **Assistant** remains untouched and Python-only; Pseudocode analysis is shown exclusively in the plugin’s **Diagnostics** tab;
- diagnostics have priority on hover; when the offending token is documented syntax, the tooltip also indicates **Ctrl+click → Documentation**;
- **Ctrl+click on language syntax** opens Documentation at that construct, while Ctrl+click on a user symbol keeps LSP go-to-definition;
- Documentation follows the **Pseudocode file language**, is generated from the core catalogue, and indexes keywords, aliases, connectors and import forms;
- the Pseudocode menu, including **Documentation**, is translated for all **45 Thonny 5 locales**, independently from source language;
- **Ctrl+Shift+I** formats (**Ctrl+Shift+F** is also accepted). Analysis is live and automatic, so there is no separate Analyze shortcut;
- Algorigramme requests the shared flowchart model from the LSP, offers whole-program/symbol scope selection and renders a real scrollable PNG asynchronously; Mermaid remains available for export; rendering is coalesced/cached so rapid Tutor stepping does not spawn redundant renders;
- Informations reports Thonny, Python, core, LSP and lexer versions plus LSP state;
- F5/Ctrl+R/Run/green triangle on `.pseudo` / `.algo` keeps the localized `!pseudo <file>` execution path; normal Python Run is untouched.
- Pseudocode ↔ Python conversion saves the generated file and immediately opens it in a new Thonny editor tab.
- source-language selection uses a read-only drop-down listing the 14 supported language names together with their ISO 639-1 codes.
- if the `pseudo-lsp` process or stdio transport fails, the adapter automatically restarts it with bounded backoff and reopens/resynchronizes every tracked Pseudocode document; restart attempts are coalesced, stale responses from replaced server processes are rejected by transport generation, and the manual restart command remains only as a recovery/debug fallback.

The package still installs as one Thonny plugin with normal transitive dependencies; Python itself is not bundled.

## What the plugin adds

`thonny-pseudocode-i18n` is deliberately a thin editor adapter. It does not contain a second parser, semantic analyser or snippet catalogue.

- `.pseudo` and `.algo` are registered as one Thonny language: `pseudocode`;
- the plugin starts the shared `pseudo-lsp` server over stdio with a small JSON-RPC client;
- diagnostics returned by the server are underlined in the editor and exposed from the dedicated **Pseudocode** view, with error/warning/information lines coloured red/orange/blue;
- **Ctrl+Space** reuses Thonny's completion popup and requests language-aware completions from `pseudo-lsp`;
- localized structural snippets are proposed according to the normal pseudocode-i18n language resolution rules;
- signature help reuses Thonny's existing calltip UI;
- pointer hover waits briefly (450 ms) and then shows the same pedagogical LSP documentation as other IDEs, including localized section labels and every accepted syntax synonym;
- **Ctrl+click** on a language keyword/connector opens **Documentation** at that construct; on a user symbol it uses `textDocument/definition`;
- syntax coloring is driven by `pygments-lexer-pseudocode-i18n` and mapped to the same native semantic tags Thonny uses for equivalent Python roles;
- a localized root **Pseudocode** menu organizes run/format/language, conversion, flowcharts, navigation, Documentation, Informations, diagnostics and language-server restart; Run shows `F5 / Ctrl+R`, Format shows `Ctrl+Shift+I / Ctrl+Shift+F`, and its UI language follows **Thonny**, independently from the source pseudocode language; the entire menu is disabled outside an active `.pseudo` / `.algo` editor while Thonny’s normal **File → Open** remains available;
- the dockable **Pseudocode** view is visible by default and orders **Diagnostics → Exécution pas à pas → Documentation → Algorigramme → Informations**; Documentation follows the source language, Tutor consumes `pseudocode/tutor`, and Algorigramme consumes `pseudocode/flowchart`;
- project-aware diagnostics resolve `math`, `random` and existing local `.pseudo` / `.algo` modules from the current document/project path, while unknown modules receive a squiggle alongside other diagnostics;
- universal `alea()` and `entalea(a, b)` are available through the shared completion/hover/signature-help vocabulary.
- normal Python editing remains handled by Thonny exactly as before.

For example, in a French file:

```pseudo
# language: fr

Fonction carré(x: réel) -> réel:
    Renvoyer x^2
Fin

Afficher carré(3)
```

press **Ctrl+Space** while editing to ask `pseudo-lsp` for completions. The language server resolves the document as French and offers the French templates from `pseudocode-i18n`.

!!! note "Snippets in Thonny 5"
    The adapter deliberately advertises `snippetSupport = false`. `pseudo-lsp` therefore converts canonical LSP snippets to safe plain-text templates before insertion. The same canonical snippet remains a real tabstop snippet in clients such as VS Code or Neovim that advertise snippet support.

## Why there is a small LSP client in this plugin

Thonny 5 stable does not yet expose the generic external-language-server proxy API present on the development branch for the next major Thonny version. This plugin therefore owns only the transport/adaptation layer needed by Thonny 5: JSON-RPC framing, document synchronization and mapping responses to Thonny UI components.

The actual language intelligence remains in `pseudocode-i18n` and `pseudocode-i18n-languageserver`. When a future stable Thonny exposes a generic LSP proxy, this adapter can be simplified without changing the language or server.


## Installation

The administrator installs **one package**:

```bash
python -m pip install 'thonny-pseudocode-i18n>=0.9.6,<0.10'
```

The package declares Thonny 5, `pseudocode-i18n`, `pseudocode-i18n-languageserver` and `pygments-lexer-pseudocode-i18n` as normal PyPI dependencies, so `pip` resolves them. Python is not embedded or downloaded by the plugin.

## Installation for development

Keep the ecosystem repositories as siblings when developing locally:

```text
pseudocode-i18n/
pygments-lexer-pseudocode-i18n/
pseudocode-i18n-languageserver/
thonny-pseudocode-i18n/
```

Then:

```bash
yarn setup
yarn bfc
```

`yarn setup` prefers the sibling 0.9.x checkouts and installs this plugin editable. Restart Thonny after installation so its plugin loader discovers `thonnycontrib.pseudocode_i18n`.

## First manual test

Create `test.algo`:

```pseudo
# language: fr

Fonction double(x: entier) -> entier:
    Renvoyer x * 2
Fin

Afficher double(21)
```

Open it in Thonny. Then verify:

1. the file is recognized as Pseudocode and colored;
2. introduce an undefined name and check that it is underlined, then use **Pseudocode → Diagnostics** and click its `Lxx` link to jump back to the source line;
3. press **Ctrl+Space** and verify localized completions/templates;
4. Ctrl+click `double` in the call to jump to its definition;
5. use **Pseudocode → Format** or **Ctrl+Shift+I** (also **Ctrl+Shift+F**);
6. use **Pseudocode → Choose language…** and verify the read-only list shows language names plus ISO 639-1 codes;
7. convert the file to Python and verify the generated `.py` file opens automatically in a new tab;
8. open **Exécution pas à pas**, step through the program and verify the source line, variables, call stack/output and synchronized algorigram update together;
9. open **Algorigramme** and verify whole-program/symbol scope selection and the rendered preview;
10. switch to a `.py` or other non-Pseudocode tab and verify that the Pseudocode menu plus all five companion tabs become disabled, then switch back;
11. use **Pseudocode → Information** and **Pseudocode → Navigation → Rename symbol…**.

## Architecture

```text
Thonny 5
  │
  └── thonny-pseudocode-i18n
        ├── file type adapter (.pseudo / .algo)
        ├── thin JSON-RPC/LSP stdio client
        ├── Pygments coloring adapter
        └── Thonny UI adapters
              │
              ▼
          pseudo-lsp
              │
              ▼
        pseudocode-i18n
```

The language definitions, parser, formatter, diagnostics, semantic index, language detection and snippets stay in `pseudocode-i18n`. The LSP protocol stays in `pseudocode-i18n-languageserver`.


### Development registration in Thonny 5

`yarn setup` installs the Python package and also exposes the checkout under Thonny 5's dedicated `thonnycontrib` plugin directory. Restart Thonny completely after running setup. On Linux, plugin loading can be diagnosed from `~/.config/Thonny/frontend.log`.

## Development

Useful commands:

```bash
yarn setup
yarn test
yarn lint
yarn dev
yarn dev:lan
yarn bfc
yarn zip
```

`package.json` is the source of truth for the project version.

## License

GNU General Public License version 3 or later (**GPL-3.0-or-later**).

## Run with Thonny

For `.pseudo` and `.algo` files, Thonny's normal **Run current script**, **F5**, **Ctrl+R** and green-triangle toolbar button are routed to the same `!pseudo <file>` CLI execution that can be typed manually in the Shell. This preserves localized Pseudocode diagnostics, source lines and interactive input instead of exposing Python/Thonny backend exceptions. Python files continue to use Thonny's ordinary execution handler unchanged.

