Metadata-Version: 2.5
Name: thonny-pseudocode-i18n
Version: 0.9.1
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.1
Requires-Dist: pseudocode-i18n<0.10,>=0.9.1
Requires-Dist: pygments-lexer-pseudocode-i18n<0.10,>=0.9.1
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.1.**
## 0.9.1 — native Thonny workflow on top of the shared LSP

Version 0.9.1 consolidates the Thonny 5 integration and documents the final 0.9 behavior:

- a dedicated **Pseudocode** root menu is translated according to the **Thonny UI language**, independently from the language of the Pseudocode source file;
- `.pseudo` and `.algo` use the same core parser, linter, type system, snippets, hover help and module resolution as VS Code;
- diagnostics underline the real offending range, multiple independent errors can be visible at once, and a diagnostic under the pointer takes priority over generic keyword help;
- pointer hover is LSP-backed, localized and exhaustive; Markdown fence markers are removed before display in Tk tooltips;
- completion keeps the canonical multilingual snippets, signature help uses Thonny calltips, and Ctrl+click navigates to definitions;
- formatting, conversion Pseudocode ↔ Python, Mermaid/SVG/PNG flowchart actions, navigation and server restart are grouped in the Pseudocode menu;
- the dockable Pseudocode view separates **Diagnostics**, **Informations** (plugin/developer information), contextual **Aide**, and **Algorigramme**;
- **F5 / Run current script / the green triangle** on `.pseudo` / `.algo` routes to the same `!pseudo <file>` CLI path used manually in the Shell, preserving localized Pseudocode errors and original source lines instead of leaking Python backend exceptions;
- normal `.py` execution remains untouched;
- `yarn setup` removes the obsolete `thonnycontrib.backend.pseudocode_i18n` development hook and stale bytecode from older 0.9 checkouts;
- Python is not bundled: installing `thonny-pseudocode-i18n` lets `pip` resolve the shared core, LSP and Pygments dependencies normally.

The plugin stays a thin Thonny adapter; language intelligence remains centralized in the core/LSP so future IDE integrations receive the same behavior.

## 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** menu;
- **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 symbol uses `textDocument/definition` and opens its definition;
- syntax coloring is driven by `pygments-lexer-pseudocode-i18n` and uses Thonny's active syntax-theme tags;
- a localized root **Pseudocode** menu organizes run/analyze/format/language, conversion, flowcharts, navigation, information, diagnostics and language-server restart; its UI language follows **Thonny**, independently from the source pseudocode language;
- the dockable **Pseudocode** view separates diagnostics, static plugin/developer information, contextual help and Mermaid flowchart output;
- 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.1,<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**;
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**;
6. 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** 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.

During development, `yarn setup` also removes the obsolete preprocessor hook `thonnycontrib.backend.pseudocode_i18n` left by older checkouts. This prevents Thonny from discovering a stale backend plugin after upgrading.
