Metadata-Version: 2.4
Name: monkeyfs
Version: 0.2.1
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"
Provides-Extra: test
Requires-Dist: pytest; 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
```

## Not a security boundary

monkeyfs is a cooperative routing layer, not a sandbox. It rebinds stdlib functions so that Python code asking for a file gets the one the active filesystem holds -- and that is the whole of it. Only Python-level file operations are intercepted: `ctypes`, `subprocess`, `socket`, `mmap`, `sqlite3` and any C extension talk to the OS directly and reach the host filesystem untouched. `monkeyfs.suspend()` is an ordinary importable that turns the routing off from inside a patched block.

So the `PermissionError -- outside root` below is a routing decision, not a wall -- useful for keeping cooperative code inside its lane, and worth nothing against code that is trying to leave. Confining untrusted code is the job of whatever controls the import surface around it -- [sandtrap](https://github.com/ashenfad/sandtrap) in this stack -- or of an OS-level boundary such as a container or a VM. monkeyfs is what those hand the confined code to read and write; it is not what keeps the code confined.

## 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
```

## ReadOnlyFS

Wraps any filesystem and blocks all write operations:

```python
from monkeyfs import VirtualFS, ReadOnlyFS, patch

vfs = VirtualFS({})
vfs.write("data.csv", b"a,b,c")

ro = ReadOnlyFS(vfs)
with patch(ro):
    print(open("data.csv").read())  # a,b,c
    open("new.txt", "w")           # PermissionError
```

## MountFS

Routes operations to different filesystems by path prefix:

```python
from monkeyfs import VirtualFS, MountFS, ReadOnlyFS, patch

base = VirtualFS({})
overlay = VirtualFS({})
overlay.write("summary.md", b"# Chapter 1")

fs = MountFS(base, {"/chapters": ReadOnlyFS(overlay)})

with patch(fs):
    # Writes go to base
    with open("app.py", "w") as f:
        f.write("print('hi')")

    # Reads from /chapters go to the overlay
    print(open("/chapters/summary.md").read())  # # Chapter 1

    # Writes to /chapters are blocked (read-only)
    open("/chapters/new.md", "w")  # PermissionError
```

## The backend protocol

A backend is any object with the right methods -- no inheritance, no base class. monkeyfs's backend protocol and [termish](https://github.com/ashenfad/termish)'s `FileSystem` protocol are the same sixteen methods with the same signatures, including the ranged `read(path, offset=0, size=-1)`. `open()` is what monkeyfs provides *over* a backend rather than something it asks for -- a file object synthesized from `read`, `write` and `stat`, lazy in binary read modes -- and a backend that has a better one (a real directory, where `fileno()` and `mmap` work) may offer its own, which monkeyfs prefers. The agreement between the two libraries is a convention enforced by tests in both, not a shared import: a third package would cost both of them their zero-dependency line for twenty lines of protocol.

So a filesystem written for either library works under the other, and under monkeyfs it is a Python `open()` for free. The conformance kit says whether yours is one:

```python
from monkeyfs import check_filesystem

check_filesystem(MyFileSystem())   # an empty one; it writes and cleans up
```

It raises `AssertionError` naming the method and what was expected of it -- including the ranged-read cases a backend that accepts `offset` and `size` and quietly ignores them would otherwise pass.

## Part of the agex stack

monkeyfs provides filesystem interception for [sandtrap](https://github.com/ashenfad/sandtrap) and [agex](https://github.com/ashenfad/agex), giving sandboxed agent code an isolated virtual filesystem. `VirtualFS` accepts any dict-like backing store -- including [kvgit](https://github.com/ashenfad/kvgit) `Staged` instances for a versioned filesystem with commit/rollback.

## Documentation

- [API Reference](docs/api.md) -- public API, FileSystem protocol, patched functions

## Development

```bash
uv sync --extra dev
uv run pytest
```

## License

MIT
