PyPI - thonny-html-highlight - Versions diffs - 0.1.0__tar.gz - Mend

thonny-html-highlight 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

thonny_html_highlight-0.1.0/PKG-INFO ADDED Viewed

@@ -0,0 +1,83 @@
+Metadata-Version: 2.3
+Name: thonny-html-highlight
+Version: 0.1.0
+Summary: Thonny plugin: syntax highlighting for HTML files
+Author: Geoff Matheson
+Author-email: Geoff Matheson <geoff.matheson@education.vic.gov.au>
+Requires-Dist: thonny>=5.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+# thonny-html-highlight
+Syntax highlighting for HTML files in the [Thonny](https://thonny.org) IDE.
+By default Thonny treats `.html` and `.htm` files as plain text. This plugin adds colour highlighting for:
+- Tag names (`div`, `span`, `a`, …)
+- Attribute names (`class`, `href`, `data-value`, …)
+- Attribute values (`"foo"`, `'bar'`, …)
+- HTML comments (`<!-- … -->`)
+- DOCTYPE declarations (`<!DOCTYPE html>`)
+- Entity references (`&amp;`, `&#169;`, `&#xA9;`, …)
+- Angle-bracket punctuation
+## Requirements
+- Thonny 5.0 or later
+- Python 3.13 or later (bundled with Thonny 5)
+## Installation
+### Via Thonny's built-in package manager (recommended)
+1. Open Thonny.
+2. Go to **Tools → Manage packages…**
+3. Search for `thonny-html-highlight`.
+4. Click **Install**.
+5. Restart Thonny.
+### Via pip / uv (command line)
+```bash
+# Using pip
+pip install thonny-html-highlight
+# Using uv
+uv pip install thonny-html-highlight
+```
+Then restart Thonny.
+### From source (development)
+```bash
+git clone https://github.com/mrmatho/thonny-html-highlight.git
+cd thonny-html-highlight
+uv pip install -e .
+```
+Restart Thonny after installing.
+## Usage
+Open any `.html` or `.htm` file in Thonny — highlighting is applied automatically. No configuration is required.
+## Known limitations
+- Content inside `<script>` and `<style>` tags is treated as HTML, which may produce incorrect highlighting for JavaScript or CSS within those blocks.
+- Colours follow Thonny's default light theme. Integration with custom syntax themes is planned for a future release.
+## Development
+```bash
+# Run tests
+uv run pytest
+# Run tests with verbose output
+uv run pytest -v
+```
+## Licence
+MIT

thonny_html_highlight-0.1.0/README.md ADDED Viewed

@@ -0,0 +1,73 @@
+# thonny-html-highlight
+Syntax highlighting for HTML files in the [Thonny](https://thonny.org) IDE.
+By default Thonny treats `.html` and `.htm` files as plain text. This plugin adds colour highlighting for:
+- Tag names (`div`, `span`, `a`, …)
+- Attribute names (`class`, `href`, `data-value`, …)
+- Attribute values (`"foo"`, `'bar'`, …)
+- HTML comments (`<!-- … -->`)
+- DOCTYPE declarations (`<!DOCTYPE html>`)
+- Entity references (`&amp;`, `&#169;`, `&#xA9;`, …)
+- Angle-bracket punctuation
+## Requirements
+- Thonny 5.0 or later
+- Python 3.13 or later (bundled with Thonny 5)
+## Installation
+### Via Thonny's built-in package manager (recommended)
+1. Open Thonny.
+2. Go to **Tools → Manage packages…**
+3. Search for `thonny-html-highlight`.
+4. Click **Install**.
+5. Restart Thonny.
+### Via pip / uv (command line)
+```bash
+# Using pip
+pip install thonny-html-highlight
+# Using uv
+uv pip install thonny-html-highlight
+```
+Then restart Thonny.
+### From source (development)
+```bash
+git clone https://github.com/mrmatho/thonny-html-highlight.git
+cd thonny-html-highlight
+uv pip install -e .
+```
+Restart Thonny after installing.
+## Usage
+Open any `.html` or `.htm` file in Thonny — highlighting is applied automatically. No configuration is required.
+## Known limitations
+- Content inside `<script>` and `<style>` tags is treated as HTML, which may produce incorrect highlighting for JavaScript or CSS within those blocks.
+- Colours follow Thonny's default light theme. Integration with custom syntax themes is planned for a future release.
+## Development
+```bash
+# Run tests
+uv run pytest
+# Run tests with verbose output
+uv run pytest -v
+```
+## Licence
+MIT

thonny_html_highlight-0.1.0/pyproject.toml ADDED Viewed

@@ -0,0 +1,24 @@
+[project]
+name = "thonny-html-highlight"
+version = "0.1.0"
+description = "Thonny plugin: syntax highlighting for HTML files"
+readme = "README.md"
+authors = [
+    { name = "Geoff Matheson", email = "geoff.matheson@education.vic.gov.au" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "thonny>=5.0",
+]
+[build-system]
+requires = ["uv_build>=0.9.7,<0.10.0"]
+build-backend = "uv_build"
+[tool.uv.build-backend]
+module-name = "thonnycontrib.html_highlight"
+module-root = "src"
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

thonny_html_highlight-0.1.0/src/thonnycontrib/html_highlight/__init__.py ADDED Viewed

@@ -0,0 +1,112 @@
+"""Thonny plugin: HTML syntax highlighting for ``.html`` / ``.htm`` files.
+When Thonny loads this plugin it calls :func:`load_plugin`, which binds
+event handlers onto the ``EditorCodeViewText`` widget class.  On every text
+change in any editor, the handler checks whether the file is HTML (by
+inspecting its path) and, if so, keeps an :class:`.HtmlHighlighter` instance
+alive on the widget and schedules a re-highlight.
+Setting ``file_type = "html"`` on the widget tells Thonny to use plain-text
+editing behaviour (simple Return, standard Backspace) rather than Python-aware
+behaviour.  It also gives future extensions (auto-indentation, tag
+auto-closing) a clean hook point.
+Widget hierarchy assumed by :func:`_get_editor_path`:
+    ``EditorCodeViewText``  →  ``CodeView``  →  ``BaseEditor``
+``BaseEditor.get_target_path()`` returns the file path or ``None`` for
+untitled buffers.
+"""
+from __future__ import annotations
+import tkinter as tk
+from .highlighter import HtmlHighlighter
+_HTML_EXTENSIONS = (".html", ".htm")
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+def _get_editor_path(text: tk.Text) -> str | None:
+    """Return the file path for *text*'s editor, or ``None`` if unavailable."""
+    try:
+        editor = text.master.master  # CodeView → BaseEditor
+        return editor.get_target_path()
+    except AttributeError:
+        return None
+def _is_html_file(text: tk.Text) -> bool:
+    """Return ``True`` when *text* is displaying an HTML file."""
+    path = _get_editor_path(text)
+    return path is not None and path.lower().endswith(_HTML_EXTENSIONS)
+# ---------------------------------------------------------------------------
+# Event handlers
+# ---------------------------------------------------------------------------
+def _on_text_change(event: tk.Event) -> None:
+    """Called on every ``<<TextChange>>`` in any editor text widget."""
+    text = event.widget
+    if not isinstance(text, tk.Text):
+        return
+    if not _is_html_file(text):
+        return
+    # Ensure this widget has a highlighter.
+    if not hasattr(text, "_html_highlighter"):
+        text._html_highlighter = HtmlHighlighter(text)
+    # Keep file_type set to "html" so Thonny uses plain-text editing
+    # behaviour.  update_file_type() resets this on save/rename, so we
+    # re-assert it on each text change.
+    if getattr(text, "file_type", None) != "html":
+        if hasattr(text, "set_file_type"):
+            text.set_file_type("html")
+    text._html_highlighter.schedule_update()
+def _on_appearance_change(event: tk.Event) -> None:
+    """Called when the user switches Thonny's syntax theme.
+    Reconfigures tag colours and re-highlights every open HTML editor so
+    that the new theme takes effect immediately.
+    """
+    from thonny import get_workbench  # noqa: PLC0415 — deferred to avoid import at test time
+    try:
+        notebook = get_workbench().get_editor_notebook()
+        for editor in notebook.get_all_editors():
+            try:
+                text = editor._code_view.text
+                hl: HtmlHighlighter | None = getattr(text, "_html_highlighter", None)
+                if hl is not None:
+                    hl.configure_tags()
+                    hl.schedule_update()
+            except Exception:
+                pass
+    except Exception:
+        pass
+# ---------------------------------------------------------------------------
+# Plugin entry point
+# ---------------------------------------------------------------------------
+def load_plugin() -> None:
+    """Register the HTML highlighting plugin with Thonny's workbench."""
+    from thonny import get_workbench  # noqa: PLC0415 — deferred to avoid import at test time
+    wb = get_workbench()
+    wb.bind_class("EditorCodeViewText", "<<TextChange>>", _on_text_change, True)
+    wb.bind("<<UpdateAppearance>>", _on_appearance_change, True)

thonny_html_highlight-0.1.0/src/thonnycontrib/html_highlight/highlighter.py ADDED Viewed

@@ -0,0 +1,149 @@
+"""Applies HTML syntax highlighting to a Thonny editor text widget.
+The :class:`HtmlHighlighter` owns all interaction with the tkinter Text
+widget.  It reads tokens from :mod:`.tokenizer` and applies named tags so
+that Thonny's theme system can override colours in the future.
+"""
+from __future__ import annotations
+import tkinter as tk
+from typing import TYPE_CHECKING, List
+from .tokenizer import Token, offsets_to_tkindices, tokenize_html
+if TYPE_CHECKING:
+    pass  # kept for future type-only imports (e.g. SyntaxText)
+# ---------------------------------------------------------------------------
+# Tag configuration
+# ---------------------------------------------------------------------------
+# Default colours for each token category.  These are intentionally chosen
+# to complement Thonny's built-in light theme; a future version will read
+# values from Thonny's syntax-theme API so that dark themes work correctly.
+_TAG_COLORS: dict[str, dict] = {
+    "html_comment":   {"foreground": "#808080"},
+    "html_doctype":   {"foreground": "#999999"},
+    "html_tag_name":  {"foreground": "#000080"},
+    "html_attr_name": {"foreground": "#912B6C"},
+    "html_attr_value":{"foreground": "#007A00"},
+    "html_entity":    {"foreground": "#007070"},
+    "html_bracket":   {"foreground": "#606060"},
+}
+# Map from tokenizer token type → tkinter tag name.
+_TOKEN_TO_TAG: dict[str, str] = {
+    "comment":   "html_comment",
+    "doctype":   "html_doctype",
+    "tag_name":  "html_tag_name",
+    "attr_name": "html_attr_name",
+    "attr_value":"html_attr_value",
+    "entity":    "html_entity",
+    "bracket":   "html_bracket",
+}
+ALL_HTML_TAGS: List[str] = list(_TOKEN_TO_TAG.values())
+# ---------------------------------------------------------------------------
+# Highlighter
+# ---------------------------------------------------------------------------
+class HtmlHighlighter:
+    """Manages HTML syntax highlighting for a single editor text widget.
+    One instance is created per text widget the first time an HTML file is
+    opened in that widget.  It is stored as ``text._html_highlighter`` so
+    that it is garbage-collected when the widget is destroyed.
+    Updating is *scheduled* rather than immediate: when :meth:`schedule_update`
+    is called (e.g. on every keystroke), it posts a single ``after_idle``
+    callback, deduplicating rapid successive calls.
+    """
+    def __init__(self, text: tk.Text) -> None:
+        self._text = text
+        self._update_scheduled = False
+        self.configure_tags()
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+    def configure_tags(self) -> None:
+        """Configure tkinter tag appearance.
+        Called once on initialisation and again whenever the Thonny
+        appearance changes (``<<UpdateAppearance>>`` event).
+        .. todo::
+            Read colours from Thonny's syntax-theme API so that dark
+            themes are respected automatically.
+        """
+        for tag, opts in _TAG_COLORS.items():
+            self._text.tag_configure(tag, **opts)
+        # HTML tags must be raised above the default text tag so they
+        # are visible.  They sit below the selection tag so selections
+        # still look normal.
+        for tag in ALL_HTML_TAGS:
+            try:
+                self._text.tag_raise(tag)
+            except tk.TclError:
+                pass  # tag may not exist yet on first call
+    def schedule_update(self) -> None:
+        """Schedule a re-highlight to run when the event loop is idle.
+        Multiple calls before the idle callback fires are collapsed into
+        one update, preventing redundant work during rapid typing.
+        """
+        if not self._update_scheduled:
+            self._update_scheduled = True
+            self._text.after_idle(self._do_update)
+    def update(self) -> None:
+        """Re-tokenise and re-highlight the full widget content immediately."""
+        self._update_scheduled = False
+        self._apply_highlighting()
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+    def _do_update(self) -> None:
+        """Idle callback — delegates to :meth:`update`."""
+        self.update()
+    def _apply_highlighting(self) -> None:
+        # Remove all existing HTML tags in one pass before adding new ones.
+        for tag in ALL_HTML_TAGS:
+            self._text.tag_remove(tag, "1.0", "end")
+        content = self._text.get("1.0", "end-1c")
+        if not content:
+            return
+        tokens: List[Token] = tokenize_html(content)
+        if not tokens:
+            return
+        # Collect every start/end offset so we can compute all tkinter
+        # indices in a single O(n) pass rather than one pass per token.
+        all_offsets = []
+        for token in tokens:
+            all_offsets.append(token.start)
+            all_offsets.append(token.end)
+        index_map = offsets_to_tkindices(content, all_offsets)
+        for token in tokens:
+            tag = _TOKEN_TO_TAG.get(token.type)
+            if tag is None:
+                continue
+            start_idx = index_map[token.start]
+            end_idx = index_map[token.end]
+            if start_idx != end_idx:
+                self._text.tag_add(tag, start_idx, end_idx)

thonny_html_highlight-0.1.0/src/thonnycontrib/html_highlight/tokenizer.py ADDED Viewed

@@ -0,0 +1,188 @@
+"""HTML tokenizer for syntax highlighting.
+Contains only pure functions — no tkinter or Thonny imports — so every
+function here can be unit-tested in complete isolation.
+"""
+from __future__ import annotations
+import re
+from typing import Dict, List, NamedTuple
+class Token(NamedTuple):
+    """A single syntax token within an HTML document.
+    Attributes:
+        type:  One of ``'comment'``, ``'doctype'``, ``'entity'``,
+               ``'bracket'``, ``'tag_name'``, ``'attr_name'``,
+               ``'attr_value'``.
+        start: Inclusive start offset in the source string.
+        end:   Exclusive end offset in the source string.
+    """
+    type: str
+    start: int
+    end: int
+# ---------------------------------------------------------------------------
+# Compiled regular expressions
+# ---------------------------------------------------------------------------
+# Matches the four top-level HTML constructs.
+#
+# The 'tag' alternative handles both opening and closing tags (including
+# self-closing).  Quoted attribute values are matched explicitly so that a
+# '>' character inside a value does not prematurely end the tag match.
+_TOP_LEVEL_RE = re.compile(
+    r"(?P<comment><!--[\s\S]*?-->)"
+    r"|(?P<doctype><!DOCTYPE[^>]*>)"
+    r"|(?P<entity>&(?:[a-zA-Z][a-zA-Z0-9]*|#\d+|#x[0-9a-fA-F]+);)"
+    r'|(?P<tag></?[a-zA-Z][a-zA-Z0-9_:-]*(?:"[^"]*"|\'[^\']*\'|[^>])*>)',
+    re.DOTALL | re.IGNORECASE,
+)
+# Parses the internal structure of a single matched tag string.
+_TAG_RE = re.compile(
+    r'^<(?P<slash>/?)(?P<name>[a-zA-Z][a-zA-Z0-9_:-]*)'
+    r'(?P<attrs>(?:"[^"]*"|\'[^\']*\'|(?!/>)[^>])*)'
+    r'(?P<end>/?>)$',
+    re.DOTALL,
+)
+# Finds individual attribute name + optional value within an attrs string.
+# The hyphen is placed at the end of the second character class so it is
+# treated as a literal rather than a range operator.
+_ATTR_RE = re.compile(
+    r'(?P<attr_name>[a-zA-Z_:][a-zA-Z0-9_.:-]*)'
+    r'(?:\s*=\s*(?P<attr_value>"[^"]*"|\'[^\']*\'|[^\s>]*))?'
+)
+# Names of the top-level alternatives, in the order they appear in _TOP_LEVEL_RE.
+_TOP_LEVEL_GROUPS = ("comment", "doctype", "entity", "tag")
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+def tokenize_html(text: str) -> List[Token]:
+    """Return a list of :class:`Token` objects for *text*, sorted by ``start``.
+    Tokens cover HTML comments, DOCTYPE declarations, entity references, tag
+    brackets, tag names, attribute names, and attribute values.
+    The function is intentionally lenient: malformed or incomplete HTML
+    produces fewer tokens rather than raising an exception.
+    .. note::
+        Content inside ``<script>`` and ``<style>`` tags is currently treated
+        as plain HTML.  Full script/style awareness is planned for a future
+        version.
+    """
+    tokens: List[Token] = []
+    for match in _TOP_LEVEL_RE.finditer(text):
+        group = _first_matched_group(match, _TOP_LEVEL_GROUPS)
+        if group == "comment":
+            tokens.append(Token("comment", match.start(), match.end()))
+        elif group == "doctype":
+            tokens.append(Token("doctype", match.start(), match.end()))
+        elif group == "entity":
+            tokens.append(Token("entity", match.start(), match.end()))
+        elif group == "tag":
+            _tokenize_tag(text, match.start(), match.end(), tokens)
+    tokens.sort(key=lambda t: t.start)
+    return tokens
+def offsets_to_tkindices(text: str, offsets: List[int]) -> Dict[int, str]:
+    """Convert character offsets into tkinter ``"line.col"`` index strings.
+    Returns a :class:`dict` mapping each offset to its index string.  Runs
+    in *O(n + k)* where *n* is ``len(text)`` and *k* is ``len(offsets)``.
+    Tkinter indices are 1-based for lines and 0-based for columns:
+    offset 0 → ``"1.0"``, the position *before* the first character.
+    """
+    if not offsets:
+        return {}
+    sorted_offsets = sorted(set(offsets))
+    result: Dict[int, str] = {}
+    line, col, pos = 1, 0, 0
+    for target in sorted_offsets:
+        while pos < target:
+            if text[pos] == "\n":
+                line += 1
+                col = 0
+            else:
+                col += 1
+            pos += 1
+        result[target] = f"{line}.{col}"
+    return result
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+def _first_matched_group(match: re.Match, names: tuple) -> str | None:
+    """Return the first name in *names* whose group actually matched."""
+    for name in names:
+        if match.group(name) is not None:
+            return name
+    return None
+def _tokenize_tag(
+    text: str, start: int, end: int, tokens: List[Token]
+) -> None:
+    """Append bracket/tag_name/attr_name/attr_value tokens for a single tag."""
+    tag_str = text[start:end]
+    m = _TAG_RE.match(tag_str)
+    if m is None:
+        # Unrecognised shape — skip rather than crash.
+        return
+    slash = m.group("slash")
+    name = m.group("name")
+    attrs = m.group("attrs")
+    closing_bracket = m.group("end")
+    # Opening bracket: '<' (1 char) or '</' (2 chars)
+    prefix_len = 2 if slash else 1
+    bracket_end = start + prefix_len
+    tokens.append(Token("bracket", start, bracket_end))
+    # Tag name
+    name_end = bracket_end + len(name)
+    tokens.append(Token("tag_name", bracket_end, name_end))
+    # Attributes (offsets relative to start of `attrs` within `text`)
+    attrs_offset = name_end
+    for attr_m in _ATTR_RE.finditer(attrs):
+        tokens.append(Token(
+            "attr_name",
+            attrs_offset + attr_m.start("attr_name"),
+            attrs_offset + attr_m.end("attr_name"),
+        ))
+        if attr_m.group("attr_value") is not None:
+            tokens.append(Token(
+                "attr_value",
+                attrs_offset + attr_m.start("attr_value"),
+                attrs_offset + attr_m.end("attr_value"),
+            ))
+    # Closing bracket: '>' or '/>'
+    close_start = end - len(closing_bracket)
+    tokens.append(Token("bracket", close_start, end))