sandfs 0.1.0__py3-none-any.whl

sandfs/__init__.py

@@ -0,0 +1,30 @@
+"""sandfs package: virtual filesystem sandbox with a mini shell."""
+
+from .vfs import VirtualFileSystem
+from .shell import SandboxShell, CommandResult
+from .pyexec import PythonExecutor, PythonExecutionResult
+from .providers import ContentProvider, DirectoryProvider, NodeContext, ProvidedNode
+from .policies import NodePolicy, VisibilityView
+from .hooks import WriteEvent, WriteHook
+from .integrations import PathEvent, PathHook
+from .adapters import MemoryStorageAdapter, StorageAdapter
+
+__all__ = [
+    "VirtualFileSystem",
+    "SandboxShell",
+    "CommandResult",
+    "PythonExecutor",
+    "PythonExecutionResult",
+    "ContentProvider",
+    "DirectoryProvider",
+    "NodeContext",
+    "ProvidedNode",
+    "NodePolicy",
+    "VisibilityView",
+    "WriteEvent",
+    "WriteHook",
+    "PathEvent",
+    "PathHook",
+    "StorageAdapter",
+    "MemoryStorageAdapter",
+]

sandfs/adapters.py

@@ -0,0 +1,58 @@
+"""Storage adapter interfaces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Mapping, Optional
+
+
+@dataclass
+class StorageEntry:
+    content: str
+    version: int = 0
+
+
+class StorageAdapter:
+    def read(self, path: str) -> StorageEntry:
+        raise NotImplementedError
+
+    def write(self, path: str, content: str, *, version: int) -> StorageEntry:
+        raise NotImplementedError
+
+    def list(self) -> Dict[str, StorageEntry]:
+        raise NotImplementedError
+
+    def delete(self, path: str) -> None:
+        raise NotImplementedError
+
+
+@dataclass
+class MemoryStorageAdapter(StorageAdapter):
+    initial: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self._entries: Dict[str, StorageEntry] = {
+            path: StorageEntry(content=text, version=0)
+            for path, text in self.initial.items()
+        }
+
+    def read(self, path: str) -> StorageEntry:
+        entry = self._entries.get(path)
+        if entry is None:
+            raise FileNotFoundError(path)
+        return StorageEntry(content=entry.content, version=entry.version)
+
+    def write(self, path: str, content: str, *, version: int) -> StorageEntry:
+        entry = self._entries.get(path)
+        if entry and entry.version != version:
+            raise ValueError("version mismatch")
+        next_version = version + 1
+        entry = StorageEntry(content=content, version=next_version)
+        self._entries[path] = entry
+        return StorageEntry(content=entry.content, version=entry.version)
+
+    def list(self) -> Dict[str, StorageEntry]:
+        return {path: StorageEntry(content=entry.content, version=entry.version) for path, entry in self._entries.items()}
+
+    def delete(self, path: str) -> None:
+        self._entries.pop(path, None)

sandfs/exceptions.py

@@ -0,0 +1,32 @@
+"""Custom exceptions for sandfs."""
+
+from __future__ import annotations
+
+
+class SandboxError(RuntimeError):
+    """Base error for the sandbox."""
+
+
+class NodeNotFound(SandboxError):
+    """Raised when a node cannot be resolved."""
+
+
+class NodeExists(SandboxError):
+    """Raised when attempting to create a node that already exists."""
+
+
+class InvalidOperation(SandboxError):
+    """Raised when an operation cannot be completed."""
+
+
+class ProviderError(SandboxError):
+    """Raised when a provider callable fails."""
+
+
+__all__ = [
+    "SandboxError",
+    "NodeNotFound",
+    "NodeExists",
+    "InvalidOperation",
+    "ProviderError",
+]

sandfs/hooks.py

@@ -0,0 +1,20 @@
+"""Hook dataclasses and type hints for persistence adapters."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+
+@dataclass(frozen=True)
+class WriteEvent:
+    path: str
+    content: str
+    version: int
+    append: bool
+
+
+WriteHook = Callable[[WriteEvent], None]
+
+
+__all__ = ["WriteEvent", "WriteHook"]

sandfs/integrations.py

@@ -0,0 +1,33 @@
+"""Integration helpers for path-scoped events."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Dict, List, TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .vfs import VirtualFileSystem
+
+
+@dataclass(frozen=True)
+class PathEvent:
+    path: str
+    event: str  # "create", "update", "delete"
+    content: str | None
+
+
+PathHook = Callable[[PathEvent], None]
+
+
+@dataclass
+class InboxRecorder:
+    events: List[Dict[str, str | None]] = field(default_factory=list)
+
+    def attach(self, vfs: "VirtualFileSystem", prefix: str) -> None:
+        vfs.register_path_hook(prefix, self._handle)
+
+    def _handle(self, event: PathEvent) -> None:
+        self.events.append({"path": event.path, "event": event.event, "content": event.content})
+
+
+__all__ = ["PathEvent", "PathHook", "InboxRecorder"]

sandfs/nodes.py

@@ -0,0 +1,166 @@
+"""Core node representations for the virtual filesystem."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import PurePosixPath
+from typing import Dict, Iterable, Iterator, Optional, TYPE_CHECKING
+
+from .exceptions import InvalidOperation, NodeExists, NodeNotFound, ProviderError
+from .policies import NodePolicy
+from .providers import ContentProvider, DirectoryProvider, NodeContext, ProvidedNode
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .vfs import VirtualFileSystem
+
+
+@dataclass
+class VirtualNode:
+    """Base node stored inside the sandbox."""
+
+    name: str
+    parent: Optional["VirtualDirectory"] = None
+    metadata: Dict[str, object] = field(default_factory=dict)
+    policy: NodePolicy = field(default_factory=NodePolicy)
+    version: int = 0
+
+    def path(self) -> PurePosixPath:
+        if self.parent is None:
+            return PurePosixPath("/")
+        segments = []
+        node: Optional[VirtualNode] = self
+        while node and node.parent is not None:
+            segments.append(node.name)
+            node = node.parent
+        return PurePosixPath("/" + "/".join(reversed(segments))) if segments else PurePosixPath("/")
+
+    def build_context(self, vfs: Optional["VirtualFileSystem"] = None) -> NodeContext:
+        return NodeContext(path=self.path(), metadata=self.metadata, vfs=vfs)
+
+
+class VirtualFile(VirtualNode):
+    """Represents a file backed by either static text or a provider."""
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        parent: Optional["VirtualDirectory"] = None,
+        content: str | None = None,
+        provider: Optional[ContentProvider] = None,
+        metadata: Optional[Dict[str, object]] = None,
+    ) -> None:
+        super().__init__(name=name, parent=parent, metadata=dict(metadata or {}))
+        self._content = content or ""
+        self._provider = provider
+
+    def read(self, vfs: Optional["VirtualFileSystem"] = None) -> str:
+        if self._provider is None:
+            return self._content
+        ctx = self.build_context(vfs)
+        try:
+            return self._provider(ctx)
+        except Exception as exc:  # pragma: no cover - rewrap provider failures
+            raise ProviderError(str(exc)) from exc
+
+    def write(self, data: str, *, append: bool = False) -> None:
+        if append:
+            self._content += data
+        else:
+            self._content = data
+        self._provider = None
+
+    def set_provider(self, provider: ContentProvider) -> None:
+        self._provider = provider
+
+
+class VirtualDirectory(VirtualNode):
+    """Directories store children lazily when a loader is present."""
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        parent: Optional["VirtualDirectory"] = None,
+        loader: Optional[DirectoryProvider] = None,
+        metadata: Optional[Dict[str, object]] = None,
+    ) -> None:
+        super().__init__(name=name, parent=parent, metadata=dict(metadata or {}))
+        self.loader = loader
+        self._loaded = loader is None
+        self.children: Dict[str, VirtualNode] = {}
+
+    def ensure_loaded(self, vfs: Optional["VirtualFileSystem"] = None) -> None:
+        if self._loaded:
+            return
+        if self.loader is None:
+            self._loaded = True
+            return
+        ctx = self.build_context(vfs)
+        snapshot = self.loader(ctx)
+        for name, provided in snapshot.items():
+            if name in self.children:
+                continue
+            self.add_child(instantiate_provided_node(name, provided, parent=self))
+        self._loaded = True
+
+    def add_child(self, node: VirtualNode) -> None:
+        if node.name in self.children:
+            raise NodeExists(f"Node {node.name} already exists in {self.path()}")
+        node.parent = self
+        self.children[node.name] = node
+
+    def remove_child(self, name: str) -> None:
+        if name not in self.children:
+            raise NodeNotFound(f"Child {name} not found in {self.path()}")
+        del self.children[name]
+
+    def get_child(self, name: str, vfs: Optional["VirtualFileSystem"] = None) -> VirtualNode:
+        self.ensure_loaded(vfs)
+        try:
+            return self.children[name]
+        except KeyError as exc:
+            raise NodeNotFound(f"Child {name} not found in {self.path()}") from exc
+
+    def iter_children(self, vfs: Optional["VirtualFileSystem"] = None) -> Iterator[VirtualNode]:
+        self.ensure_loaded(vfs)
+        return iter(self.children.values())
+
+
+def instantiate_provided_node(
+    name: str,
+    provided: ProvidedNode,
+    *,
+    parent: Optional[VirtualDirectory],
+) -> VirtualNode:
+    if provided.kind == "file":
+        node = VirtualFile(name=name, parent=parent, metadata=provided.metadata)
+        if provided.content_provider:
+            node.set_provider(provided.content_provider)
+        else:
+            node.write(provided.content or "")
+        if provided.policy is not None:
+            node.policy = provided.policy
+        return node
+    if provided.kind == "dir":
+        node = VirtualDirectory(
+            name=name,
+            parent=parent,
+            loader=provided.directory_provider,
+            metadata=provided.metadata,
+        )
+        if provided.children:
+            for child_name, child in provided.children.items():
+                node.add_child(instantiate_provided_node(child_name, child, parent=node))
+        if provided.policy is not None:
+            node.policy = provided.policy
+        return node
+    raise InvalidOperation(f"Unknown provided node kind: {provided.kind}")
+
+
+__all__ = [
+    "VirtualNode",
+    "VirtualFile",
+    "VirtualDirectory",
+    "instantiate_provided_node",
+]

sandfs/policies.py

@@ -0,0 +1,55 @@
+"""Policy and visibility helpers for sandfs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import FrozenSet, Iterable, Optional, Set
+
+
+@dataclass
+class NodePolicy:
+    """Controls access, write semantics, and visibility for a node."""
+
+    readable: bool = True
+    writable: bool = True
+    append_only: bool = False
+    classification: str = "public"
+    principals: Set[str] = field(default_factory=set)
+
+
+@dataclass(frozen=True)
+class VisibilityView:
+    """Filters nodes by classification labels and principals."""
+
+    classifications: Optional[FrozenSet[str]] = None
+    principals: Optional[FrozenSet[str]] = None
+
+    def __init__(
+        self,
+        classifications: Optional[Iterable[str]] = None,
+        principals: Optional[Iterable[str]] = None,
+    ) -> None:
+        object.__setattr__(
+            self,
+            "classifications",
+            frozenset(classifications) if classifications is not None else None,
+        )
+        object.__setattr__(
+            self,
+            "principals",
+            frozenset(principals) if principals is not None else None,
+        )
+
+    def allows(self, policy: NodePolicy) -> bool:
+        if policy.principals:
+            if self.principals is None:
+                return False
+            if not (policy.principals & self.principals):
+                return False
+            return True
+        if self.classifications is None:
+            return True
+        return policy.classification in self.classifications
+
+
+__all__ = ["NodePolicy", "VisibilityView"]

sandfs/providers.py

@@ -0,0 +1,82 @@
+"""Provider protocols and helper dataclasses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import PurePosixPath
+from typing import Any, Callable, Dict, Iterable, Literal, Mapping, MutableMapping, Optional
+
+if False:  # pragma: no cover - for type checkers only
+    from .vfs import VirtualFileSystem
+from .policies import NodePolicy
+
+
+@dataclass(frozen=True)
+class NodeContext:
+    """Context passed to providers when materializing nodes."""
+
+    path: PurePosixPath
+    metadata: Mapping[str, Any]
+    vfs: Optional["VirtualFileSystem"] = None
+
+
+ContentProvider = Callable[[NodeContext], str]
+DirectoryProvider = Callable[[NodeContext], "DirectorySnapshot"]
+DirectorySnapshot = Mapping[str, "ProvidedNode"]
+
+
+@dataclass
+class ProvidedNode:
+    """Represents a node returned by a directory provider."""
+
+    kind: Literal["file", "dir"]
+    content: Optional[str] = None
+    content_provider: Optional[ContentProvider] = None
+    directory_provider: Optional[DirectoryProvider] = None
+    children: Optional[MutableMapping[str, "ProvidedNode"]] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    policy: Optional[NodePolicy] = None
+
+    @staticmethod
+    def file(
+        *,
+        content: Optional[str] = None,
+        content_provider: Optional[ContentProvider] = None,
+        metadata: Optional[Mapping[str, Any]] = None,
+        policy: Optional[NodePolicy] = None,
+    ) -> "ProvidedNode":
+        return ProvidedNode(
+            kind="file",
+            content=content,
+            content_provider=content_provider,
+            metadata=dict(metadata or {}),
+            policy=policy,
+        )
+
+    @staticmethod
+    def directory(
+        *,
+        children: Optional[Mapping[str, "ProvidedNode"]] = None,
+        directory_provider: Optional[DirectoryProvider] = None,
+        metadata: Optional[Mapping[str, Any]] = None,
+        policy: Optional[NodePolicy] = None,
+    ) -> "ProvidedNode":
+        frozen_children = None
+        if children is not None:
+            frozen_children = {name: child for name, child in children.items()}
+        return ProvidedNode(
+            kind="dir",
+            children=frozen_children,
+            directory_provider=directory_provider,
+            metadata=dict(metadata or {}),
+            policy=policy,
+        )
+
+
+__all__ = [
+    "NodeContext",
+    "ContentProvider",
+    "DirectoryProvider",
+    "DirectorySnapshot",
+    "ProvidedNode",
+]

sandfs/pyexec.py

@@ -0,0 +1,82 @@
+"""Helper to execute Python snippets inside the sandbox."""
+
+from __future__ import annotations
+
+import contextlib
+import io
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+from .vfs import VirtualFileSystem
+
+
+_ALLOWED_BUILTINS = {
+    "abs": abs,
+    "all": all,
+    "any": any,
+    "bool": bool,
+    "dict": dict,
+    "enumerate": enumerate,
+    "float": float,
+    "int": int,
+    "len": len,
+    "list": list,
+    "map": map,
+    "max": max,
+    "min": min,
+    "print": print,
+    "range": range,
+    "repr": repr,
+    "reversed": reversed,
+    "round": round,
+    "set": set,
+    "sorted": sorted,
+    "str": str,
+    "sum": sum,
+    "tuple": tuple,
+    "zip": zip,
+}
+
+
+@dataclass
+class PythonExecutionResult:
+    stdout: str
+    globals: Dict[str, Any]
+
+
+class PythonExecutor:
+    def __init__(
+        self,
+        vfs: VirtualFileSystem,
+        *,
+        builtins: Optional[Dict[str, Any]] = None,
+        globals_template: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self.vfs = vfs
+        self._builtins = dict(_ALLOWED_BUILTINS)
+        if builtins:
+            self._builtins.update(builtins)
+        base = {"vfs": vfs, "fs": vfs}
+        if globals_template:
+            base.update(globals_template)
+        self._globals_template = base
+
+    def run(
+        self,
+        code: str,
+        *,
+        filename: str = "<sandbox>",
+        extra_globals: Optional[Dict[str, Any]] = None,
+    ) -> PythonExecutionResult:
+        env: Dict[str, Any] = dict(self._globals_template)
+        if extra_globals:
+            env.update(extra_globals)
+        env["__builtins__"] = dict(self._builtins)
+        stdout = io.StringIO()
+        with contextlib.redirect_stdout(stdout):
+            exec(compile(code, filename, "exec"), env, env)
+        env.pop("__builtins__", None)
+        return PythonExecutionResult(stdout=stdout.getvalue(), globals=env)
+
+
+__all__ = ["PythonExecutor", "PythonExecutionResult"]