Run tree-sitter parsing as a background task.

Tree-sitter's incremental parsing is not always fast enough to be
executed for every editing keystroke without providing a very poor user
experience. For example:

```python

"""Docstring with closing quotes not yet added <cursor here>

import textual
...
```

Typing into the above docstring can become very slow. For a 25,000 line
Python file on my laptop, each change causes a reparse time of about 0.2
- 0.3 seconds: editing is painful.

This change decouples incremental parsing from TextArea edits, using
tree-sitter's timeout mechanism and a task to effectivley run parsing in
the background, on a snapshot of the TextAreas's contents. While parsing
is in progress, editing of the TextArea text continues in a responsive
manner.

Edits to the tree-siiter parse tree are buffered until the background
parser is able to process them, while edits to the displayed text are
applied as they occur.

Author: paul-ollis

CHANGELOG.md

@@ -68,8 +68,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   single colour. Now the 'px' appears in a different colour to the rest of the
   text.
 
-- Fixed a cause of slow editing for syntax highlighed TextArea widgets with
-  large documents.
+- Fixed some situations where editing for syntax highlighed TextArea widgets with
+  large documents was very unresponsive.
 
 
 ## [2.1.2] - 2025-02-26

src/textual/document/_document.py

@@ -3,7 +3,7 @@
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from functools import lru_cache
-from typing import TYPE_CHECKING, NamedTuple, Tuple, overload
+from typing import TYPE_CHECKING, Callable, NamedTuple, Tuple, overload
 
 from typing_extensions import Literal, get_args
 
@@ -140,6 +140,12 @@ def get_size(self, indent_width: int) -> Size:
             The Size of the document bounding box.
         """
 
+    def clean_up(self) -> None:
+        """Perform any pre-deletion clean up.
+
+        The default implementation does nothing.
+        """
+
     def query_syntax_tree(
         self,
         query: "Query",
@@ -162,6 +168,27 @@ def query_syntax_tree(
         """
         return {}
 
+    def set_syntax_tree_update_callback(
+        callback: Callable[[], None],
+    ) -> None:
+        """Set a callback function for signalling a rebuild of the syntax tree.
+
+        The default implementation does nothing.
+
+        Args:
+            callback: A function that takes no arguments and returns None.
+        """
+
+    def trigger_syntax_tree_update(self, force_update: bool = False) -> None:
+        """Trigger a new syntax tree update to run in the background.
+
+        The default implementation does nothing.
+
+        Args:
+            force_update: When set, ensure that the syntax tree is regenerated
+                unconditionally.
+        """
+
     def prepare_query(self, query: str) -> "Query | None":
         return None
 

src/textual/document/_syntax_aware_document.py

@@ -1,7 +1,10 @@
 from __future__ import annotations
 
+import weakref
+from asyncio import CancelledError, Event, Task, create_task, sleep
 from contextlib import contextmanager
-from typing import ContextManager
+from functools import partial
+from typing import Callable, ContextManager, NamedTuple
 
 try:
     from tree_sitter import Language, Node, Parser, Query, Tree
@@ -43,6 +46,17 @@ def temporary_query_point_range(
         query.set_point_range(default_point_range)
 
 
+class SyntaxTreeEdit(NamedTuple):
+    """Details of a tree-sitter syntax tree edit operation."""
+
+    start_byte: int
+    old_end_byte: int
+    new_end_byte: int
+    start_point: int
+    old_end_point: int
+    new_end_point: int
+
+
 class SyntaxAwareDocumentError(Exception):
     """General error raised when SyntaxAwareDocument is used incorrectly."""
 
@@ -76,9 +90,37 @@ def __init__(
         self._parser = Parser(self.language)
         """The tree-sitter Parser or None if tree-sitter is unavailable."""
 
-        self._syntax_tree: Tree = self._parser.parse(self._read_callable)  # type: ignore
+        self._syntax_tree: Tree = self._parser.parse(
+            partial(self._read_callable, lines=self.lines)
+        )  # type: ignore
         """The tree-sitter Tree (syntax tree) built from the document."""
 
+        self._syntax_tree_update_callback: Callable[[], None] | None = None
+        self._background_parser = BackgroundSyntaxParser(self)
+        self._pending_syntax_edits: list[SyntaxTreeEdit] = []
+
+    def clean_up(self) -> None:
+        """Perform any pre-deletion clean up."""
+        self._background_parser.stop()
+
+    def copy_of_lines(self):
+        """Provide a copy of the document's lines."""
+        return list(self._lines)
+
+    def apply_pending_syntax_edits(self) -> bool:
+        """Apply any pending edits to the syntax tree.
+
+        Returns:
+            True if any edits were applied.
+        """
+        if self._pending_syntax_edits:
+            for edit in self._pending_syntax_edits:
+                self._syntax_tree.edit(**edit._asdict())
+            self._pending_syntax_edits[:] = []
+            return True
+        else:
+            return False
+
     def prepare_query(self, query: str) -> Query | None:
         """Prepare a tree-sitter tree query.
 
@@ -117,6 +159,26 @@ def query_syntax_tree(
         with temporary_query_point_range(query, start_point, end_point):
             return query.captures(self._syntax_tree.root_node)
 
+    def set_syntax_tree_update_callback(
+        self,
+        callback: Callable[[], None],
+    ) -> None:
+        """Set a callback function for signalling a rebuild of the syntax tree.
+
+        Args:
+            callback: A function that takes no arguments and returns None.
+        """
+        self._syntax_tree_update_callback = callback
+
+    def trigger_syntax_tree_update(self, force_update: bool = False) -> None:
+        """Trigger a new syntax tree update to run in the background.
+
+        Args:
+            force_update: When set, ensure that the syntax tree is regenerated
+                unconditionally.
+        """
+        self._background_parser.trigger_syntax_tree_update(force_update)
+
     def replace_range(self, start: Location, end: Location, text: str) -> EditResult:
         """Replace text at the given range.
 
@@ -143,22 +205,47 @@ def replace_range(self, start: Location, end: Location, text: str) -> EditResult
         end_location = replace_result.end_location
         assert self._syntax_tree is not None
         assert self._parser is not None
-        self._syntax_tree.edit(
-            start_byte=start_byte,
-            old_end_byte=old_end_byte,
-            new_end_byte=start_byte + text_byte_length,
-            start_point=start_point,
-            old_end_point=old_end_point,
-            new_end_point=self._location_to_point(end_location),
-        )
-        # Incrementally parse the document.
-        self._syntax_tree = self._parser.parse(
-            self._read_callable,
-            self._syntax_tree,  # type: ignore[arg-type]
+        self._pending_syntax_edits.append(
+            SyntaxTreeEdit(
+                start_byte=start_byte,
+                old_end_byte=old_end_byte,
+                new_end_byte=start_byte + text_byte_length,
+                start_point=start_point,
+                old_end_point=old_end_point,
+                new_end_point=self._location_to_point(end_location),
+            )
         )
-
         return replace_result
 
+    def reparse(self, timeout_us: int, lines: list[str], syntax_tree=None) -> bool:
+        """Reparse the document.
+
+        Args:
+            timeout_us: The parser timeout in microseconds.
+            lines: A list of the lines being parsed.
+
+        Returns:
+            True if parsing succeeded and False if a timeout occurred.
+        """
+        assert timeout_us > 0
+        read_source = partial(self._read_callable, lines=lines)
+        tree = self._syntax_tree
+        saved_timeout = self._parser.timeout_micros
+        try:
+            self._parser.timeout_micros = timeout_us
+            try:
+                tree = self._parser.parse(read_source, tree)  # type: ignore[arg-type]
+            except ValueError:
+                # The only known cause is a timeout.
+                return False
+            else:
+                self._syntax_tree = tree
+                if self._syntax_tree_update_callback is not None:
+                    self._syntax_tree_update_callback()
+                return True
+        finally:
+            self._parser.timeout_micros = saved_timeout
+
     def get_line(self, index: int) -> str:
         """Return the string representing the line, not including new line characters.
 
@@ -214,7 +301,12 @@ def _location_to_point(self, location: Location) -> tuple[int, int]:
             bytes_on_left = 0
         return row, bytes_on_left
 
-    def _read_callable(self, byte_offset: int, point: tuple[int, int]) -> bytes:
+    def _read_callable(
+        self,
+        byte_offset: int,
+        point: tuple[int, int],
+        lines: list[str],
+    ) -> bytes:
         """A callable which informs tree-sitter about the document content.
 
         This is passed to tree-sitter which will call it frequently to retrieve
@@ -224,14 +316,14 @@ def _read_callable(self, byte_offset: int, point: tuple[int, int]) -> bytes:
             byte_offset: The number of (utf-8) bytes from the start of the document.
             point: A tuple (row index, column *byte* offset). Note that this differs
                 from our Location tuple which is (row_index, column codepoint offset).
+            lines: The lines of the document being parsed.
 
         Returns:
             All the utf-8 bytes between the byte_offset/point and the end of the current
                 line _including_ the line separator character(s). Returns None if the
                 offset/point requested by tree-sitter doesn't correspond to a byte.
         """
         row, column = point
-        lines = self._lines
         newline = self.newline
 
         row_out_of_bounds = row >= len(lines)
@@ -252,3 +344,75 @@ def _read_callable(self, byte_offset: int, point: tuple[int, int]) -> bytes:
                 return b"\n"
 
         return b""
+
+
+class BackgroundSyntaxParser:
+    """A provider of incremental background parsing for syntax highlighting.
+
+    This runs tree-sitter parsing as a parallel, background asyncio task. This
+    prevents occasional, relatively long parsing times from making `TextArea`
+    editing become unresponsive.
+    """
+
+    PARSE_TIME_SLICE = 0.005
+    PARSE_TIMEOUT_MICROSECONDS = int(PARSE_TIME_SLICE * 1_000_000)
+
+    def __init__(self, document: SyntaxAwareDocument):
+        self._document_ref = weakref.ref(document)
+        self._event = Event()
+        self._task: Task = create_task(self._execute_reparsing())
+        self._force_update = False
+
+    def stop(self):
+        """Stop running as a background task."""
+        self._task.cancel()
+
+    def trigger_syntax_tree_update(self, force_update: bool) -> None:
+        """Trigger a new syntax tree update to run in the background.
+
+        Args:
+            force_update: When set, ensure that the syntax tree is regenerated
+                unconditionally.
+        """
+        if force_update:
+            self._force_update = True
+        self._event.set()
+
+    async def _execute_reparsing(self) -> None:
+        """Run, as a task, tree-sitter reparse operations on demand."""
+        while True:
+            try:
+                try:
+                    await self._event.wait()
+                except Exception as e:
+                    return
+                self._event.clear()
+                force_update = self._force_update
+                self._force_update = False
+                await self._perform_a_single_reparse(force_update)
+            except CancelledError:
+                return
+
+    async def _perform_a_single_reparse(self, force_update: bool) -> None:
+        document = self._document_ref()
+        if document is None:
+            return
+        if not (document.apply_pending_syntax_edits() or force_update):
+            return
+
+        # In order to allow the user to continue editing without interruption, we reparse
+        # a snapshot of the TextArea's document.
+        copy_of_text_for_parsing = document.copy_of_lines()
+
+        # Use tree-sitter's parser timeout mechanism, when necessary, break the
+        # full reparse into multiple steps. Most of the time, tree-sitter is so
+        # fast that no looping occurs.
+        parsed_ok = False
+        while not parsed_ok:
+            parsed_ok = document.reparse(
+                self.PARSE_TIMEOUT_MICROSECONDS, lines=copy_of_text_for_parsing
+            )
+            if not parsed_ok:
+                # Sleeping for zero seconds allows other tasks, I/O, *etc.* to execute,
+                # keeping the TextArea and other widgets responsive.
+                await sleep(0.0)