robotcode-core 2.6.1__tar.gz → 2.7.0__tar.gz

{robotcode_core-2.6.1 → robotcode_core-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: robotcode-core
-Version: 2.6.1
+Version: 2.7.0
 Summary: Some core classes for RobotCode
 Project-URL: Homepage, https://robotcode.io
 Project-URL: Donate, https://opencollective.com/robotcode

robotcode_core-2.7.0/src/robotcode/core/__version__.py

@@ -0,0 +1 @@
+__version__ = "2.7.0"

{robotcode_core-2.6.1 → robotcode_core-2.7.0}/src/robotcode/core/documents_manager.py

@@ -9,6 +9,7 @@ from typing import (
     Iterator,
     List,
     Optional,
+    Tuple,
     Union,
 )
 
@@ -17,8 +18,11 @@ from .event import event
 from .language import LanguageDefinition, language_id_filter
 from .lsp.types import DocumentUri
 from .text_document import TextDocument
-from .uri import Uri
+from .uri import InvalidUriError, Uri
 from .utils.logging import LoggingDescriptor
+from .utils.path import DiskInfo, disk_info_from_stat
+
+_STAT_VERIFY_MAX_RETRIES: Final = 3
 
 
 class CantReadDocumentError(Exception):
@@ -58,6 +62,39 @@ class DocumentsManager:
 
         raise FileNotFoundError(str(uri))
 
+    def read_document_text_with_disk_info(
+        self, uri: Uri, language_id: Union[str, Callable[[Any], bool], None]
+    ) -> Tuple[str, Optional[DiskInfo]]:
+        """Read document text and capture a stat snapshot bound to that exact content.
+
+        Uses a stat → read → stat-verify protocol: when the file changes while it
+        is being read, the read is retried. Returns ``None`` as info when no
+        consistent snapshot could be captured (non-file URI, stat error, or the
+        file never settled) — such text must not be persisted to or validated
+        against a disk cache.
+        """
+        try:
+            path = uri.to_path()
+            st_before = os.stat(path)
+        except (InvalidUriError, OSError):
+            return self.read_document_text(uri, language_id), None
+
+        text = self.read_document_text(uri, language_id)
+
+        for _ in range(_STAT_VERIFY_MAX_RETRIES):
+            try:
+                st_after = os.stat(path)
+            except OSError:
+                return text, None
+
+            if (st_before.st_mtime_ns, st_before.st_size) == (st_after.st_mtime_ns, st_after.st_size):
+                return text, disk_info_from_stat(st_after)
+
+            st_before = st_after
+            text = self.read_document_text(uri, language_id)
+
+        return text, None
+
     def detect_language_id(self, path_or_uri: Union[str, "os.PathLike[Any]", Uri]) -> str:
         path = path_or_uri.to_path() if isinstance(path_or_uri, Uri) else Path(path_or_uri)
 
@@ -84,11 +121,13 @@ class DocumentsManager:
             return result
 
         try:
+            text, disk_info = self.read_document_text_with_disk_info(uri, language_id)
             return self._append_document(
                 document_uri=DocumentUri(uri),
                 language_id=language_id or self.detect_language_id(path),
-                text=self.read_document_text(uri, language_id),
+                text=text,
                 version=version,
+                disk_info=disk_info,
             )
         except (SystemExit, KeyboardInterrupt):
             raise
@@ -147,12 +186,14 @@ class DocumentsManager:
         text: str,
         language_id: Optional[str] = None,
         version: Optional[int] = None,
+        disk_info: Optional[DiskInfo] = None,
     ) -> TextDocument:
         result = TextDocument(
             document_uri=document_uri,
             language_id=language_id,
             text=text,
             version=version,
+            disk_info=disk_info,
         )
 
         result.cache_invalidate.add(self._on_document_cache_invalidate)
@@ -166,6 +207,7 @@ class DocumentsManager:
         language_id: str,
         text: str,
         version: Optional[int] = None,
+        disk_info: Optional[DiskInfo] = None,
     ) -> TextDocument:
         with self._lock:
             document = self._create_document(
@@ -173,6 +215,7 @@ class DocumentsManager:
                 language_id=language_id,
                 text=text,
                 version=version,
+                disk_info=disk_info,
             )
 
             self._documents[document_uri] = document

{robotcode_core-2.6.1 → robotcode_core-2.7.0}/src/robotcode/core/text_document.py

@@ -24,6 +24,7 @@ from robotcode.core.event import event
 from robotcode.core.lsp.types import DocumentUri, Position, Range
 from robotcode.core.uri import Uri
 from robotcode.core.utils.logging import LoggingDescriptor
+from robotcode.core.utils.path import DiskInfo
 
 
 def is_multibyte_char(char: str) -> bool:
@@ -108,6 +109,7 @@ class TextDocument:
         text: str,
         language_id: Optional[str] = None,
         version: Optional[int] = None,
+        disk_info: Optional[DiskInfo] = None,
     ) -> None:
         super().__init__()
 
@@ -119,6 +121,7 @@ class TextDocument:
         self._text = text
         self._orig_text = text
         self._orig_version = version
+        self._disk_info = disk_info
         self._lines: Optional[List[str]] = None
         self._cache: Dict[weakref.ref[Any], CacheEntry] = collections.defaultdict(CacheEntry)
         self._data_lock = RLock(name=f"Document.data_lock '{document_uri}'", default_timeout=120)
@@ -143,6 +146,16 @@ class TextDocument:
         with self._lock:
             return self._text
 
+    @property
+    def disk_info(self) -> Optional[DiskInfo]:
+        """Stat snapshot of the disk content this document's text was read from.
+
+        ``None`` means the text is not known to match any disk state (e.g. it
+        came from the editor or the file changed while it was being read).
+        """
+        with self._lock:
+            return self._disk_info
+
     def save(self, version: Optional[int], text: Optional[str]) -> None:
         self.apply_full_change(version, text, save=True)
 
@@ -158,7 +171,14 @@ class TextDocument:
             self._lines = None
 
     @_logger.call
-    def apply_full_change(self, version: Optional[int], text: Optional[str], *, save: bool = False) -> None:
+    def apply_full_change(
+        self,
+        version: Optional[int],
+        text: Optional[str],
+        *,
+        save: bool = False,
+        disk_info: Optional[DiskInfo] = None,
+    ) -> None:
         with self._cache_invalidating():
             if version is not None:
                 self._version = version
@@ -167,11 +187,14 @@ class TextDocument:
                 self._lines = None
             if save:
                 self._orig_text = self._text
+            if text is not None or save:
+                self._disk_info = disk_info
 
     @_logger.call
     def apply_incremental_change(self, version: Optional[int], range: Range, text: str) -> None:
         with self._cache_invalidating():
             try:
+                self._disk_info = None
                 if version is not None:
                     self._version = version
 
@@ -371,6 +394,7 @@ class TextDocument:
 
     def _clear(self) -> None:
         self._lines = None
+        self._disk_info = None
         self._invalidate_data()
 
     @_logger.call

{robotcode_core-2.6.1 → robotcode_core-2.7.0}/src/robotcode/core/utils/path.py

@@ -1,8 +1,10 @@
 import os
 import re
 import sys
+import time
+from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Optional, Tuple, Union
+from typing import Any, Final, Optional, Tuple, Union
 
 
 def path_is_relative_to(
@@ -88,3 +90,57 @@ def same_file_id(
     if id1 is None or id2 is None:
         return False
     return id1 == id2
+
+
+RACY_MTIME_EPSILON_NS: Final = 2_000_000_000
+"""Snapshot age below which a file state is not trusted for persistent caching.
+
+Analogous to git's "racily clean" handling: if a file's mtime is within this
+epsilon of the current time when its content is read, a later write could land
+in the same filesystem timestamp tick and leave mtime and size unchanged, so
+the snapshot must not be persisted. 2 s covers the coarsest common filesystem
+timestamp granularity (FAT).
+
+Known limitation: the age is computed against the local clock, so on a network
+mount whose server clock trails the client by more than the epsilon a
+just-written file already counts as trusted — the stat-only design cannot
+detect that; a content hash would be required to close it.
+"""
+
+
+@dataclass(frozen=True)
+class DiskInfo:
+    """Stat snapshot taken at the moment file content was read from disk.
+
+    Equality compares only ``mtime_ns`` and ``size`` — ``trusted`` describes the
+    capture moment (see ``RACY_MTIME_EPSILON_NS``), not the file state, and must
+    never influence comparisons of stored metadata against fresh probes.
+
+    Deliberately carries no ``st_ino``: file IDs are 0 or unstable on
+    FAT/exFAT/ReFS and change across SMB/FUSE remounts, which would invalidate
+    caches spuriously; the racy-mtime guard already covers the same-tick
+    rewrite case an inode check would catch.
+    """
+
+    mtime_ns: int
+    size: int
+    trusted: bool = field(default=True, compare=False)
+
+
+def disk_info_from_stat(st: os.stat_result, now_ns: Optional[int] = None) -> DiskInfo:
+    if now_ns is None:
+        now_ns = time.time_ns()
+    return DiskInfo(
+        mtime_ns=st.st_mtime_ns,
+        size=st.st_size,
+        # a negative age (mtime in the future, e.g. clock skew) is also untrusted
+        trusted=now_ns - st.st_mtime_ns >= RACY_MTIME_EPSILON_NS,
+    )
+
+
+def probe_disk_info(path: Union[str, "os.PathLike[str]"]) -> Optional[DiskInfo]:
+    """Return the current :class:`DiskInfo` for *path*, or ``None`` on error."""
+    try:
+        return disk_info_from_stat(os.stat(path))
+    except OSError:
+        return None

robotcode_core-2.6.1/src/robotcode/core/__version__.py

@@ -1 +0,0 @@
-__version__ = "2.6.1"