py_fs_shell

Python virtual filesystem primitives for agent workflows, tests, and sandboxed file operations.

It provides:

  • InMemoryFs for ephemeral virtual filesystems
  • LocalFileSystem for sandboxed real-disk access
  • Workspace for metadata + blob backed storage
  • FileSystemStateBackend for JSON, search/replace, diffs, archives, hashing, and edit planning

Installation

With uv:

uv add py-fs-shell

With pip:

pip install py-fs-shell

For S3-backed workspaces:

uv add 'py-fs-shell[s3]'
pip install 'py-fs-shell[s3]'

For local development from this repository:

uv sync --extra dev --extra s3

Examples

In-memory workspace:

import asyncio
from py_fs_shell import StateWriteEditInstruction, workspace

async def main():
    ws = await workspace.memory()
    state = ws.state()

    await state.write_file("/src/main.py", "print('hello world')\n")
    await state.write_json("/config.json", {"debug": True})

    matches = await state.search_files("**/*.py", "hello")
    print(matches[0].path)

    plan = await state.plan_edits([
        StateWriteEditInstruction(
            path="/README.md",
            content="# Demo\n",
        ),
    ])
    await state.apply_edit_plan(plan)

    await state.write_file_bytes("/video.mp4", b"video bytes")

asyncio.run(main())

Local workspace:

import asyncio
from pathlib import Path
from py_fs_shell import workspace

async def main():
    ws = await workspace.local(Path(".py_fs_shell_workspace"))
    state = ws.state()

    await state.write_file("/notes/todo.md", "- ship release\n")
    await state.write_json("/metadata.json", {"backend": "local"})

    print(await state.read_file("/notes/todo.md"))

asyncio.run(main())

To reclaim orphaned blobs left behind by older workspace versions, run:

result = await ws.garbage_collect_blobs()
print(result.deleted, result.deleted_keys)

Current versions also clean up unreferenced blobs automatically on file overwrite/delete.

S3-backed workspace:

import asyncio
from py_fs_shell import workspace

async def main():
    ws = await workspace.s3(bucket="my-bucket", prefix="runs/123")
    state = ws.state()

    await state.write_file("/outputs/result.txt", "done\n")
    await state.write_json("/metadata.json", {"backend": "s3"})

    print(await state.read_file("/outputs/result.txt"))

asyncio.run(main())

Releases

Releases are tracked with semversioner. See RELEASE.md and CHANGELOG.md.

License

MIT. See LICENSE.

Inspired by Cloudflare's @cloudflare/shell package.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for abdulmuminyaqeen from gravatar.com abdulmuminyaqeen

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Provides Extra

dev s3

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

py_fs_shell-0.0.3.tar.gz (80.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

py_fs_shell-0.0.3-py3-none-any.whl (34.5 kB view details)

Uploaded Python 3

File details

Details for the file py_fs_shell-0.0.3.tar.gz.

File metadata

  • Download URL: py_fs_shell-0.0.3.tar.gz
  • Upload date:
  • Size: 80.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for py_fs_shell-0.0.3.tar.gz
Algorithm Hash digest
SHA256 3255dec57c618fbd11c9fa79a4b87d3b40d6a50382c4d44c7b8af22d1f6563eb
MD5 7318bcdfc2787cf3fc8168a324e20b91
BLAKE2b-256 56e35776c80a5859f1756c7a1da7b951227df94c5749f55700a051493549358f

See more details on using hashes here.

Provenance

The following attestation bundles were made for py_fs_shell-0.0.3.tar.gz:

Publisher: release.yml on Abdulmumin1/py-fs-shell

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file py_fs_shell-0.0.3-py3-none-any.whl.

File metadata

  • Download URL: py_fs_shell-0.0.3-py3-none-any.whl
  • Upload date:
  • Size: 34.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for py_fs_shell-0.0.3-py3-none-any.whl
Algorithm Hash digest
SHA256 01c396e3fca968cbaa44fd2b5009446cfd6de6aec12540ce77c19d946d120ab1
MD5 fd0b4ebba5f2a524d9223f3c343cb198
BLAKE2b-256 a97ccb6573443b52b586fa32ab7163c8925d6996857a9ae5964ee805f3099bab

See more details on using hashes here.

Provenance

The following attestation bundles were made for py_fs_shell-0.0.3-py3-none-any.whl:

Publisher: release.yml on Abdulmumin1/py-fs-shell

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.0.3 This release

2 files

0.0.2

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page