monkeyfs 0.1.0__tar.gz

monkeyfs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Ashenfelter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

monkeyfs-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: monkeyfs
+Version: 0.1.0
+Summary: Transparent filesystem interception via monkey-patching.
+Author: ashenfad
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ashenfad/monkeyfs
+Project-URL: Bug Tracker, https://github.com/ashenfad/monkeyfs/issues
+Project-URL: Documentation, https://github.com/ashenfad/monkeyfs#readme
+Project-URL: Source, https://github.com/ashenfad/monkeyfs
+Keywords: filesystem,monkey-patch,sandbox,vfs,interception
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Filesystems
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-timeout; extra == "test"
+Dynamic: license-file
+
+# monkeyfs 🐒
+
+Filesystem interception via monkey-patching.
+
+Patches `open()`, `os.listdir()`, `os.stat()`, and 30+ other stdlib functions to route through a virtual or isolated filesystem. Patches are applied lazily on first `patch()` call and are inert outside the context. Uses `contextvars` for async-safe isolation between concurrent tasks. Zero dependencies.
+
+## Install
+
+```bash
+pip install monkeyfs
+```
+
+## Quick example
+
+```python
+from monkeyfs import VirtualFS, patch
+
+vfs = VirtualFS({})
+
+with patch(vfs):
+    with open("data.csv", "w") as f:
+        f.write("name,score\nalice,98\nbob,87\n")
+
+    import os
+    print(os.listdir("/"))        # ['data.csv']
+    print(os.path.getsize("data.csv"))  # 30
+
+    with open("data.csv") as f:
+        print(f.read())           # name,score\nalice,98\nbob,87\n
+```
+
+## IsolatedFS
+
+Restricts file operations to a root directory on the real filesystem:
+
+```python
+from monkeyfs import IsolatedFS, patch
+
+isolated = IsolatedFS(root="/tmp/sandbox")
+
+with patch(isolated):
+    with open("notes.txt", "w") as f:
+        f.write("hello")          # Written to /tmp/sandbox/notes.txt
+
+    open("/etc/passwd")           # PermissionError -- outside root
+```
+
+## Documentation
+
+- [API Reference](docs/api.md) -- public API, FileSystem protocol, patched functions
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+```
+
+## License
+
+MIT

monkeyfs-0.1.0/README.md

@@ -0,0 +1,61 @@
+# monkeyfs 🐒
+
+Filesystem interception via monkey-patching.
+
+Patches `open()`, `os.listdir()`, `os.stat()`, and 30+ other stdlib functions to route through a virtual or isolated filesystem. Patches are applied lazily on first `patch()` call and are inert outside the context. Uses `contextvars` for async-safe isolation between concurrent tasks. Zero dependencies.
+
+## Install
+
+```bash
+pip install monkeyfs
+```
+
+## Quick example
+
+```python
+from monkeyfs import VirtualFS, patch
+
+vfs = VirtualFS({})
+
+with patch(vfs):
+    with open("data.csv", "w") as f:
+        f.write("name,score\nalice,98\nbob,87\n")
+
+    import os
+    print(os.listdir("/"))        # ['data.csv']
+    print(os.path.getsize("data.csv"))  # 30
+
+    with open("data.csv") as f:
+        print(f.read())           # name,score\nalice,98\nbob,87\n
+```
+
+## IsolatedFS
+
+Restricts file operations to a root directory on the real filesystem:
+
+```python
+from monkeyfs import IsolatedFS, patch
+
+isolated = IsolatedFS(root="/tmp/sandbox")
+
+with patch(isolated):
+    with open("notes.txt", "w") as f:
+        f.write("hello")          # Written to /tmp/sandbox/notes.txt
+
+    open("/etc/passwd")           # PermissionError -- outside root
+```
+
+## Documentation
+
+- [API Reference](docs/api.md) -- public API, FileSystem protocol, patched functions
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+```
+
+## License
+
+MIT

monkeyfs-0.1.0/monkeyfs/__init__.py

@@ -0,0 +1,23 @@
+"""monkeyfs: Transparent filesystem interception via monkey-patching."""
+
+from .base import FileInfo, FileMetadata, FileSystem
+from .config import FSConfig, IsolatedFSConfig, VirtualFSConfig, connect_fs
+from .context import current_fs, suspend
+from .isolated import IsolatedFS
+from .patching import patch
+from .virtual import VirtualFS
+
+__all__ = [
+    "connect_fs",
+    "current_fs",
+    "FileInfo",
+    "FileMetadata",
+    "FileSystem",
+    "FSConfig",
+    "IsolatedFS",
+    "IsolatedFSConfig",
+    "patch",
+    "suspend",
+    "VirtualFS",
+    "VirtualFSConfig",
+]

monkeyfs-0.1.0/monkeyfs/base.py

@@ -0,0 +1,159 @@
+"""Base filesystem interface and dataclasses.
+
+Defines the common interface for filesystem implementations (VirtualFS, IsolatedFS).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass
+class FileMetadata:
+    """Metadata for a single file or directory.
+
+    Attributes:
+        size: File size in bytes (0 for directories).
+        created_at: ISO 8601 timestamp when file was created (UTC).
+        modified_at: ISO 8601 timestamp when file was last modified (UTC).
+        is_dir: True if this is a directory, False for files.
+    """
+
+    size: int
+    created_at: str
+    modified_at: str
+    is_dir: bool = False
+
+    # os.stat_result-compatible properties — allows FileMetadata to be
+    # returned directly from stat() when used with sandtrap's os.stat() patch.
+
+    @property
+    def st_size(self) -> int:
+        return self.size
+
+    @property
+    def st_mode(self) -> int:
+        return 0o040755 if self.is_dir else 0o100644
+
+    @property
+    def st_ino(self) -> int:
+        return 0
+
+    @property
+    def st_dev(self) -> int:
+        return 0
+
+    @property
+    def st_nlink(self) -> int:
+        return 1
+
+    @property
+    def st_uid(self) -> int:
+        return os.getuid() if hasattr(os, "getuid") else 0
+
+    @property
+    def st_gid(self) -> int:
+        return os.getgid() if hasattr(os, "getgid") else 0
+
+    def _parse_ts(self, iso_str: str) -> float:
+        try:
+            return datetime.fromisoformat(iso_str).timestamp()
+        except ValueError:
+            return 0.0
+
+    @property
+    def st_atime(self) -> float:
+        return self._parse_ts(self.modified_at)
+
+    @property
+    def st_mtime(self) -> float:
+        return self._parse_ts(self.modified_at)
+
+    @property
+    def st_ctime(self) -> float:
+        return self._parse_ts(self.created_at)
+
+
+@dataclass
+class FileInfo:
+    """Complete file information for UI display.
+
+    Attributes:
+        name: File or directory name (basename).
+        path: Full path to file or directory.
+        size: File size in bytes (0 for directories).
+        created_at: ISO 8601 timestamp when created (UTC).
+        modified_at: ISO 8601 timestamp when last modified (UTC).
+        is_dir: True if this is a directory, False if file.
+    """
+
+    name: str
+    path: str
+    size: int
+    created_at: str
+    modified_at: str
+    is_dir: bool
+
+
+@runtime_checkable
+class FileSystem(Protocol):
+    """Minimal interface for patch() patching.
+
+    Only methods that the patching layer dispatches to are listed here.
+    Implementations may (and typically do) have additional methods like
+    read(), write(), glob(), list_detailed(), etc. — those are
+    application-level concerns, not part of the interception contract.
+
+    Required — patching will fail without these:
+    """
+
+    def open(self, path: str, mode: str = "r", **kwargs: Any) -> Any:
+        """Open a file."""
+        ...
+
+    def stat(self, path: str) -> FileMetadata:
+        """Get file metadata."""
+        ...
+
+    def exists(self, path: str) -> bool:
+        """Check if path exists."""
+        ...
+
+    def isfile(self, path: str) -> bool:
+        """Check if path is a file."""
+        ...
+
+    def isdir(self, path: str) -> bool:
+        """Check if path is a directory."""
+        ...
+
+    def list(self, path: str = ".", recursive: bool = False) -> list[str]:
+        """List directory contents (filenames only)."""
+        ...
+
+    def remove(self, path: str) -> None:
+        """Remove a file."""
+        ...
+
+    def mkdir(self, path: str, parents: bool = False, exist_ok: bool = False) -> None:
+        """Create a directory."""
+        ...
+
+    def makedirs(self, path: str, exist_ok: bool = True) -> None:
+        """Create directory tree."""
+        ...
+
+    def rename(self, src: str, dst: str) -> None:
+        """Rename/move a file or directory."""
+        ...
+
+    def getcwd(self) -> str:
+        """Get current working directory."""
+        ...
+
+    def chdir(self, path: str) -> None:
+        """Change current working directory."""
+        ...

monkeyfs-0.1.0/monkeyfs/config.py

@@ -0,0 +1,98 @@
+"""Configuration for filesystem access.
+
+Provides configuration dataclasses and connect_fs factory function for
+configuring filesystem access (virtual or isolated).
+"""
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass
+class VirtualFSConfig:
+    """Configuration for virtual (in-memory) filesystem.
+
+    Attributes:
+        type: Always "virtual".
+        max_size_mb: Maximum total size of all files in megabytes.
+            None means unlimited.
+    """
+
+    type: Literal["virtual"] = "virtual"
+    max_size_mb: int | None = None
+
+
+@dataclass
+class IsolatedFSConfig:
+    """Configuration for isolated (real) filesystem with path restriction.
+
+    Attributes:
+        type: Always "isolated".
+        root: Absolute path to root directory (all file operations restricted to this path).
+    """
+
+    type: Literal["isolated"] = "isolated"
+    root: str = ""
+
+
+# Type alias for all filesystem configs
+FSConfig = VirtualFSConfig | IsolatedFSConfig
+
+
+def connect_fs(
+    type: Literal["virtual", "isolated"] = "virtual",
+    **kwargs,
+) -> FSConfig:
+    """Configure filesystem access.
+
+    Creates a filesystem configuration.
+
+    Args:
+        type: FileSystem type.
+            - "virtual": In-memory filesystem backed by a mapping.
+                        Files persist with state and participate in versioning.
+            - "isolated": Real filesystem restricted to a directory.
+                         Requires 'root' argument.
+        **kwargs: Additional configuration for the filesystem type.
+            For type="virtual":
+                - max_size_mb (int): Optional. Max total file size in MB.
+            For type="isolated":
+                - root (str): Required. Absolute path to root directory.
+
+    Returns:
+        FSConfig for initialization.
+
+    Examples:
+        Virtual filesystem:
+        >>> connect_fs(type="virtual")
+        VirtualFSConfig(type='virtual', max_size_mb=None)
+
+        Isolated filesystem:
+        >>> connect_fs(type="isolated", root="/path/to/project")
+        IsolatedFSConfig(type='isolated', root='/path/to/project')
+    """
+    if type == "virtual":
+        max_size_mb = kwargs.pop("max_size_mb", None)
+        if kwargs:
+            raise ValueError(
+                f"Unexpected arguments for virtual fs: {list(kwargs.keys())}"
+            )
+        return VirtualFSConfig(type=type, max_size_mb=max_size_mb)
+
+    elif type == "isolated":
+        root = kwargs.pop("root", "")
+
+        if kwargs:
+            raise ValueError(
+                f"Unexpected arguments for isolated fs: {list(kwargs.keys())}"
+            )
+
+        if not root:
+            raise ValueError("Isolated filesystem requires 'root' parameter")
+
+        return IsolatedFSConfig(root=root)
+
+    else:
+        raise ValueError(
+            f"Unsupported filesystem type: {type}. Use 'virtual' or 'isolated'."
+        )

monkeyfs-0.1.0/monkeyfs/context.py

@@ -0,0 +1,29 @@
+"""Context variables for filesystem isolation.
+
+Shared context variables used by patching.py and filesystem implementations
+to coordinate filesystem routing and prevent recursion loops.
+"""
+
+import contextvars
+from contextlib import contextmanager
+from typing import Any, Iterator
+
+# Context variable holding the current filesystem
+current_fs: contextvars.ContextVar[Any] = contextvars.ContextVar(
+    "monkeyfs_current_fs", default=None
+)
+
+
+@contextmanager
+def suspend() -> Iterator[None]:
+    """Temporarily disable filesystem interception in the current context.
+
+    Use this when implementing internal filesystem operations (like inside
+    IsolatedFS) that need to perform real I/O without triggering the
+    patched functions recursively.
+    """
+    token = current_fs.set(None)
+    try:
+        yield
+    finally:
+        current_fs.reset(token)