monkeyfs 0.1.0

Transparent filesystem interception via monkey-patching.

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

pip install monkeyfs

Quick example

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:

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 -- public API, FileSystem protocol, patched functions

Development

uv sync --extra dev
uv run pytest

License

MIT