mint-sdk 1.2.2__tar.gz → 1.2.4__tar.gz

{mint_sdk-1.2.2 → mint_sdk-1.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mint-sdk
-Version: 1.2.2
+Version: 1.2.4
 Summary: MINT Plugin SDK - Build analysis plugins for the MINT (Mass-spec INtegrated Toolkit) platform
 Project-URL: Homepage, https://github.com/MorscherLab/MINT
 Project-URL: Documentation, https://github.com/MorscherLab/MINT/tree/main/packages/sdk-python#readme

{mint_sdk-1.2.2 → mint_sdk-1.2.4}/src/mint_sdk/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.2.2'
-__version_tuple__ = version_tuple = (1, 2, 2)
+__version__ = version = '1.2.4'
+__version_tuple__ = version_tuple = (1, 2, 4)
 
 __commit_id__ = commit_id = None

{mint_sdk-1.2.2 → mint_sdk-1.2.4}/src/mint_sdk/docs/bundled/frontend.json

@@ -1,6 +1,6 @@
 {
   "sdk": "frontend",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "categories": {
     "components": [
       {
@@ -15274,7 +15274,7 @@
         "params": [
           {
             "name": "options",
-            "type": "{ apiBaseUrl?: string }"
+            "type": "FilePickerAdapterOptions & { apiBaseUrl?: string }"
           }
         ],
         "returnType": "PickerAdapter",
@@ -18426,6 +18426,12 @@
     {
       "name": "FilePicker"
     },
+    {
+      "name": "FilePickerAdapterOptions"
+    },
+    {
+      "name": "FilePickerTransport"
+    },
     {
       "name": "FileSelection"
     },
@@ -20262,6 +20268,9 @@
     {
       "name": "createElisaAssayCollection"
     },
+    {
+      "name": "createFilePickerAdapter"
+    },
     {
       "name": "createFlowCytometryAssayCollection"
     },

{mint_sdk-1.2.2 → mint_sdk-1.2.4}/src/mint_sdk/filesystem.py

@@ -12,11 +12,17 @@ that do not match without the listing ever misreporting what is on disk.
 from __future__ import annotations
 
 import os
-from collections.abc import Iterable, Sequence
-from dataclasses import dataclass
+import stat
+from collections import OrderedDict
+from collections.abc import Iterable, Mapping, Sequence
+from concurrent.futures import Future
+from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from enum import StrEnum
+from math import isfinite
 from pathlib import Path, PurePosixPath
+from threading import Lock
+from time import monotonic
 
 from pydantic import BaseModel, ConfigDict
 
@@ -130,6 +136,18 @@ class DirectoryListing(BaseModel):
     truncated: bool = False
 
 
+@dataclass
+class _DirectorySnapshot:
+    entries: list[DirectoryEntry]
+    signature: tuple[int, ...]
+    timestamp: float
+    child_counts: dict[str, int | None] = field(default_factory=dict)
+    count_lock: Lock = field(default_factory=Lock)
+
+
+_CacheKey = tuple[str, Path, Path, PurePosixPath, bool]
+
+
 def normalize_type_rules(rules: Iterable[str] | None) -> frozenset[str]:
     """Normalize user-facing extensions to lowercase, dot-prefixed suffixes.
 
@@ -168,6 +186,8 @@ def _relative_parts(path: str) -> tuple[str, ...]:
     if not cleaned:
         return ()
     parts = tuple(part for part in cleaned.split("/") if part not in {"", "."})
+    if any(part[1:2] == ":" and part[0].lower() in "abcdefghijklmnopqrstuvwxyz" for part in parts):
+        raise MountPathError("A mount path must not contain a Windows drive")
     if any(part == ".." for part in parts):
         raise MountPathError("A mount path must not escape its mount root")
     return parts
@@ -177,7 +197,7 @@ def _resolved_root(mount: ServerMount) -> Path:
     """Resolve a mount root, treating an absent or unreadable one as offline."""
     try:
         root = mount.root.resolve(strict=True)
-    except OSError as exc:
+    except (OSError, RuntimeError) as exc:
         raise MountPathNotFoundError(f"Mount {mount.id!r} is not available") from exc
     if not root.is_dir():
         raise MountPathNotFoundError(f"Mount {mount.id!r} is not available")
@@ -187,23 +207,10 @@ def _resolved_root(mount: ServerMount) -> Path:
 def _is_available(mount: ServerMount) -> bool:
     try:
         return mount.root.is_dir()
-    except OSError:
+    except (OSError, RuntimeError):
         return False
 
 
-def _child_count(path: Path, *, include_hidden: bool) -> int | None:
-    """Count a directory's entries, or None when it cannot be read.
-
-    Hidden entries are counted only when the listing itself would show them, so
-    the number beside a folder agrees with what opening it displays.
-    """
-    try:
-        with os.scandir(path) as entries:
-            return sum(1 for item in entries if include_hidden or not item.name.startswith("."))
-    except OSError:
-        return None
-
-
 def _matches_rules(name: str, extension: str, rules: frozenset[str]) -> bool:
     """Test a filename against the type rules.
 
@@ -225,6 +232,13 @@ class FileBrowser:
     The mount list is deployment configuration supplied by the host platform.
     Everything a caller passes afterwards — mount id, path, type rules — is
     treated as untrusted input.
+
+    Directory metadata is cached for ``cache_ttl`` seconds (zero disables
+    retention), bounded by ``cache_size`` directories. Every request resolves
+    its path and checks the directory signature before reusing metadata.
+    ``refresh=True`` or ``clear_cache`` also invalidates descendant listings.
+    Optional ``child_count_type_rules`` maps entry kinds to countable suffixes;
+    missing kinds or empty rules count nothing. ``None`` counts every visible entry.
     """
 
     def __init__(
@@ -232,14 +246,47 @@ class FileBrowser:
         mounts: Sequence[ServerMount],
         *,
         type_rules: Iterable[str] | None = None,
-        max_entries: int = 2000,
+        max_entries: int | None = 2000,
         child_count_limit: int = 250,
+        child_count_type_rules: Mapping[EntryKind, Iterable[str]] | None = None,
+        cache_ttl: float = 300,
+        cache_size: int = 128,
+        restrict_symlinks_to_directory: bool = False,
     ) -> None:
+        if not isfinite(cache_ttl) or cache_ttl < 0:
+            raise ValueError("cache_ttl must be finite and non-negative")
+        if not isinstance(cache_size, int) or isinstance(cache_size, bool) or cache_size < 1:
+            raise ValueError("cache_size must be a positive integer")
+        if max_entries is not None and (not isinstance(max_entries, int) or max_entries < 1):
+            raise ValueError("max_entries must be a positive integer or None")
+        if child_count_limit < 0:
+            raise ValueError("child_count_limit must be non-negative")
         self._mounts = tuple(mounts)
         self._by_id = {mount.id: mount for mount in self._mounts}
         self._default_type_rules = normalize_type_rules(type_rules)
         self._max_entries = max_entries
         self._child_count_limit = child_count_limit
+        self._child_count_type_rules = (
+            {EntryKind(kind): normalize_type_rules(rules) for kind, rules in child_count_type_rules.items()}
+            if child_count_type_rules is not None else None
+        )
+        self._cache_ttl = cache_ttl
+        self._cache_size = cache_size
+        self._restrict_symlinks_to_directory = restrict_symlinks_to_directory
+        # ponytail: bounded by directory count; add an entry budget if very wide mounts exceed memory limits.
+        self._cache: OrderedDict[_CacheKey, _DirectorySnapshot] = OrderedDict()
+        self._pending: dict[_CacheKey, tuple[tuple[int, ...], Future[_DirectorySnapshot]]] = {}
+        self._cache_lock = Lock()
+
+    def clear_cache(self, mount_id: str | None = None) -> None:
+        """Invalidate listings and detach in-flight scans so they cannot refill the cache."""
+        if mount_id is not None:
+            self._mount(mount_id)
+        with self._cache_lock:
+            for mapping in (self._cache, self._pending):
+                for key in list(mapping):
+                    if mount_id is None or key[0] == mount_id:
+                        del mapping[key]
 
     def list_mounts(self) -> list[MountInfo]:
         """Describe every configured mount, flagging the ones that are offline."""
@@ -265,12 +312,13 @@ class FileBrowser:
         candidate = root.joinpath(*parts)
         try:
             resolved = candidate.resolve(strict=True)
-        except OSError as exc:
+        except (OSError, RuntimeError) as exc:
             raise MountPathNotFoundError(f"{path!r} does not exist in mount {mount_id!r}") from exc
         # Resolve-then-compare: `parts` is already free of "..", so anything
         # landing outside the root got there through a symlink.
         if resolved != root and not resolved.is_relative_to(root):
             raise MountPathError(f"{path!r} would escape mount {mount_id!r}")
+        _relative_parts(resolved.relative_to(root).as_posix())
         return resolved
 
     def list_directory(
@@ -283,6 +331,8 @@ class FileBrowser:
         sort: SortKey = SortKey.NAME,
         descending: bool = False,
         include_hidden: bool = False,
+        refresh: bool = False,
+        count_children: bool = True,
     ) -> DirectoryListing:
         """List one directory inside a mount.
 
@@ -291,15 +341,39 @@ class FileBrowser:
         a caller can honestly report "N items, M shown".
         """
         mount = self._mount(mount_id)
+        parts = _relative_parts(path)
+        if not include_hidden and any(part.startswith(".") for part in parts):
+            raise MountPathError("Hidden directories are not included")
         directory = self.resolve(mount_id, path)
-        if not directory.is_dir():
+        root = _resolved_root(mount)
+        if not directory.is_relative_to(root):
+            raise MountPathError(f"{path!r} would escape mount {mount_id!r}")
+        if not include_hidden and any(part.startswith(".") for part in directory.relative_to(root).parts):
+            raise MountPathError("Hidden directories are not included")
+        try:
+            directory_stat = directory.stat(follow_symlinks=False)
+        except (OSError, RuntimeError) as exc:
+            raise MountPathNotFoundError(f"{path!r} does not exist in mount {mount_id!r}") from exc
+        if not stat.S_ISDIR(directory_stat.st_mode):
             raise MountPathError(f"{path!r} is not a directory in mount {mount_id!r}")
 
         rules = self._default_type_rules if type_rules is None else normalize_type_rules(type_rules)
-        base = PurePosixPath(*_relative_parts(path))
-        root = _resolved_root(mount)
-
-        entries = self._scan(directory, root, base, rules, include_hidden=include_hidden)
+        base = PurePosixPath(*parts)
+        if refresh:
+            self.clear_cache(mount_id)
+        key = (mount_id, root, directory, base, include_hidden)
+        signature = (
+            directory_stat.st_dev, directory_stat.st_ino,
+            directory_stat.st_mtime_ns, directory_stat.st_ctime_ns, directory_stat.st_size,
+        )
+        snapshot = self._directory_snapshot(key, signature)
+        entries = [
+            entry.model_copy(update={
+                "matches_type_rules": entry.kind is EntryKind.DIRECTORY
+                or _matches_rules(entry.name, entry.extension, rules),
+            })
+            for entry in snapshot.entries
+        ]
         total_count = len(entries)
         match_count = sum(1 for entry in entries if entry.matches_type_rules)
 
@@ -314,11 +388,12 @@ class FileBrowser:
 
         # Cap after sorting so the cut is deterministic, and say so rather than
         # silently returning a short listing.
-        truncated = len(entries) > self._max_entries
+        truncated = self._max_entries is not None and len(entries) > self._max_entries
         if truncated:
             entries = entries[: self._max_entries]
 
-        entries = self._count_children(directory, entries, include_hidden=include_hidden)
+        if count_children:
+            entries = self._count_children(directory, entries, snapshot, root=root, include_hidden=include_hidden)
 
         return DirectoryListing(
             mount_id=mount_id,
@@ -338,12 +413,53 @@ class FileBrowser:
         except KeyError as exc:
             raise MountNotFoundError(f"unknown mount {mount_id!r}") from exc
 
+    def _directory_snapshot(self, key: _CacheKey, signature: tuple[int, ...]) -> _DirectorySnapshot:
+        _, root, directory, base, include_hidden = key
+        with self._cache_lock:
+            cached = self._cache.get(key)
+            if (
+                cached is not None
+                and cached.signature == signature
+                and monotonic() - cached.timestamp < self._cache_ttl
+            ):
+                self._cache.move_to_end(key)
+                return cached
+            existing = self._pending.get(key)
+            owner = existing is None or existing[0] != signature
+            if owner:
+                future: Future[_DirectorySnapshot] = Future()
+                self._pending[key] = (signature, future)
+            else:
+                future = existing[1]
+        if not owner:
+            return future.result()
+        try:
+            snapshot = _DirectorySnapshot(
+                self._scan(directory, root, base, include_hidden=include_hidden),
+                signature, monotonic(),
+            )
+            with self._cache_lock:
+                if self._pending.get(key) == (signature, future):
+                    if self._cache_ttl:
+                        self._cache[key] = snapshot
+                        self._cache.move_to_end(key)
+                        while len(self._cache) > self._cache_size:
+                            self._cache.popitem(last=False)
+                    del self._pending[key]
+            future.set_result(snapshot)
+            return snapshot
+        except BaseException as exc:
+            with self._cache_lock:
+                if self._pending.get(key) == (signature, future):
+                    del self._pending[key]
+            future.set_exception(exc)
+            raise
+
     def _scan(
         self,
         directory: Path,
         root: Path,
         base: PurePosixPath,
-        rules: frozenset[str],
         *,
         include_hidden: bool,
     ) -> list[DirectoryEntry]:
@@ -353,7 +469,7 @@ class FileBrowser:
                 for item in scan:
                     if not include_hidden and item.name.startswith("."):
                         continue
-                    entry = self._describe(item, root, base, rules)
+                    entry = self._describe(item, root, base, directory=directory, include_hidden=include_hidden)
                     if entry is not None:
                         entries.append(entry)
         except OSError as exc:
@@ -369,7 +485,9 @@ class FileBrowser:
         self,
         directory: Path,
         entries: list[DirectoryEntry],
+        snapshot: _DirectorySnapshot,
         *,
+        root: Path,
         include_hidden: bool,
     ) -> list[DirectoryEntry]:
         """Fill in child counts, but only when the directory is small enough.
@@ -382,10 +500,23 @@ class FileBrowser:
         directories = [entry for entry in entries if entry.kind is EntryKind.DIRECTORY]
         if len(directories) > self._child_count_limit:
             return entries
-        counted = {
-            entry.path: _child_count(directory / entry.name, include_hidden=include_hidden)
-            for entry in directories
-        }
+        # Only this directory's count work is serialized; unrelated scans stay concurrent.
+        with snapshot.count_lock:
+            for entry in directories:
+                if entry.path in snapshot.child_counts:
+                    continue
+                count = None
+                try:
+                    target = (directory / entry.name).resolve(strict=True)
+                    boundary = directory if self._restrict_symlinks_to_directory else root
+                    if target.is_relative_to(boundary) and (
+                        include_hidden or not any(part.startswith(".") for part in target.relative_to(root).parts)
+                    ):
+                        count = self._child_count(target, root=root, include_hidden=include_hidden)
+                except (OSError, RuntimeError):
+                    pass
+                snapshot.child_counts[entry.path] = count
+            counted = dict(snapshot.child_counts)
         return [
             entry.model_copy(update={"child_count": counted[entry.path]})
             if entry.path in counted
@@ -393,26 +524,89 @@ class FileBrowser:
             for entry in entries
         ]
 
+    def _child_count(self, directory: Path, *, root: Path, include_hidden: bool) -> int | None:
+        """Count matching children without retaining another directory snapshot."""
+        rules_by_kind = self._child_count_type_rules
+        count = 0
+        try:
+            with os.scandir(directory) as items:
+                for item in items:
+                    try:
+                        if not include_hidden and item.name.startswith("."):
+                            continue
+                        if _relative_parts(item.name) != (item.name,):
+                            continue
+                        lowered = item.name.lower()
+                        if rules_by_kind is not None and not any(
+                            lowered.endswith(rule) for rules in rules_by_kind.values() for rule in rules
+                        ):
+                            continue
+                        if item.is_symlink() or item.is_junction():
+                            entry = self._describe(
+                                item, root, PurePosixPath(), directory=directory, include_hidden=include_hidden,
+                            )
+                            if entry is None:
+                                continue
+                            kind = entry.kind
+                        elif rules_by_kind is None:
+                            count += 1
+                            continue
+                        elif item.is_dir(follow_symlinks=False):
+                            kind = EntryKind.DIRECTORY
+                        elif item.is_file(follow_symlinks=False):
+                            kind = EntryKind.FILE
+                        else:
+                            continue
+                        if rules_by_kind is None or any(
+                            lowered.endswith(rule) for rule in rules_by_kind.get(kind, ())
+                        ):
+                            count += 1
+                    except (OSError, RuntimeError, ValueError):
+                        continue
+            return count
+        except OSError:
+            return None
+
     def _describe(
         self,
         item: os.DirEntry[str],
         root: Path,
         base: PurePosixPath,
-        rules: frozenset[str],
+        *,
+        directory: Path,
+        include_hidden: bool,
     ) -> DirectoryEntry | None:
         """Build one entry, or None when it is unreadable or points outside."""
         try:
+            if _relative_parts(item.name) != (item.name,):
+                return None
             # A symlink out of the mount is not part of the mount. Drop it
             # rather than listing something the caller could never open.
-            if item.is_symlink() and not Path(item.path).resolve().is_relative_to(root):
+            if item.is_symlink() or item.is_junction():
+                target = Path(item.path).resolve(strict=True)
+                boundary = directory if self._restrict_symlinks_to_directory else root
+                if not target.is_relative_to(boundary):
+                    return None
+                target_parts = _relative_parts(target.relative_to(root).as_posix())
+                if not include_hidden and any(part.startswith(".") for part in target_parts):
+                    return None
+                stat_result = target.stat(follow_symlinks=False)
+            else:
+                # Do not follow an entry that was replaced with a link after scandir.
+                stat_result = item.stat(follow_symlinks=False)
+            if hasattr(stat_result, "st_reparse_tag") and stat_result.st_reparse_tag in (
+                stat.IO_REPARSE_TAG_MOUNT_POINT, stat.IO_REPARSE_TAG_SYMLINK,
+            ):
+                # A resolved target or ordinary entry may have become a junction meanwhile.
+                return None
+            is_dir = stat.S_ISDIR(stat_result.st_mode)
+            if not is_dir and not stat.S_ISREG(stat_result.st_mode):
                 return None
-            is_dir = item.is_dir()
-            stat_result = item.stat()
             # Inside the guard: an out-of-range mtime raises OSError too, and
             # one corrupt entry should be skipped like any other unreadable
             # one rather than failing the whole directory.
             modified_at = datetime.fromtimestamp(stat_result.st_mtime, tz=UTC)
-        except (OSError, ValueError, OverflowError):
+        except (OSError, RuntimeError, ValueError, OverflowError):
             return None
 
         kind = EntryKind.DIRECTORY if is_dir else EntryKind.FILE
@@ -426,7 +620,7 @@ class FileBrowser:
             extension=extension,
             # A directory is always reachable: type rules describe what you can
             # pick, not where you can go.
-            matches_type_rules=is_dir or _matches_rules(item.name, extension, rules),
+            matches_type_rules=True,
             child_count=None,
         )