How tg1482/loopy works
What this project is (type + purpose)
Loopy is a Python library (plus a CLI-like REPL) that implements a sandbox “filesystem” whose entire state lives in a single Python string. It provides:
• An in-memory tree model (directories/files/symlinks)
• A parser/serializer between that tree and a single raw string representation (XML-ish tags)
• A filesystem-like API (mkdir, touch, ls, cat, rm, mv, grep, find, glob, etc.)
• A bash-style shell runner (loopy.shell.run) with pipes and chaining, plus a REPL (python -m loopy.shell …)
• An optional file-backed mode that persists the raw string to a .loopy file (FileBackedLoopy, load, save)
File tree-driven architecture (what the directories imply)
From the tree:
• src/loopy/
• core.py, core_v2.py: likely the domain model + operations (tree nodes, path resolution, CRUD, search, serialization)
• file_store.py: persistence adapter (load/save .loopy, file-backed wrapper)
• shell.py: command parsing/execution and REPL entry
• __init__.py: public exports (Loopy, FileBackedLoopy, helpers)
• examples/: sample datasets (*.loopy) and notebook
• tests/: unit tests spanning core, shell, file store, stress/perf
• stress_test.py: perf benchmark harness
• .github/workflows/tests.yml: CI pipeline to run tests
• pyproject.toml: packaging + dependencies + entry points (if any)
This structure strongly suggests a clean separation:
Core Loopy engine ↔ Shell interface ↔ File storage adapter.
Input raw string (optional)
⟶ Parser
⟶ In-memory Node Tree (authoritative state)
User operations / shell commands
⟶ Core operations mutate tree
Serialization on demand
⟶ Tree ⟶ .raw string (cached until invalidated by mutation)
Shell flow
• Shell run("...") / REPL input
⟶ parse into commands
⟶ execute against Loopy instance
⟶ optionally pipe outputs between commands
⟶ return final output string(s)
File-backed flow
• Mutation command (touch, mkdir, rm, …) against FileBackedLoopy
⟶ Core mutation
⟶ triggers save() (writes .loopy file)
Architectural patterns to highlight (specific to Loopy)
• Core/Adapter separation
• Core = deterministic, in-memory, no OS I/O
• Adapter = file_store for persistence side effects
• Command pattern / interpreter
• shell commands mapped to core operations
• pipelines/chaining as composition mechanism
• Lazy serialization + cache invalidation
• .raw generated on demand
• cached .raw reused until mutation
• Iterative algorithms
• README claims “no recursion limits”; useful to note for deep trees
What “detailed and separated into many components” means here (practical checklist)
• Loopy object (public API)
• Node Tree (state)
• Path resolution + cwd
• CRUD ops (mkdir/touch/rm/mv/cp/ln)
• Search ops (grep/find/glob)
• Parser (raw → tree)
• Serializer (tree → raw)
• Raw cache + invalidation on mutation
• shell.run() API
• Shell parser
• Shell executor
• Pipe/chaining engine
• REPL entry (python -m loopy.shell …)
• load() / save()
• FileBackedLoopy autosave behavior
• .loopy file on disk (external resource)
• Examples (examples/*.loopy) as sample inputs (optional but useful)
• CI/tests/benchmarks as non-runtime support (optional layer)