Filesystem

The fs module provides capability-typed filesystem access with Result returns:

import fs

def example() -> Result[None, FsError] {
    let wp = fs.write_path("/tmp/demo.txt")?
    let _w = fs.write_text(wp, "hello")?
    let rp = fs.read_path("/tmp/demo.txt")?
    let content = fs.read_text(rp)?
    return Ok(None)
}

Path Constructors

Create typed paths before performing operations. Each constructor validates capabilities at construction time:

Constructor	Returns	Validation
fs.path(s)	Path	None (neutral type)
fs.read_path(s)	Result[ReadPath, FsError]	Must exist and be readable
fs.write_path(s)	Result[WritePath, FsError]	Parent must be writable
fs.dir_path(s)	Result[DirPath, FsError]	Must exist and be a directory
fs.root(s)	Result[RootDir, FsError]	Must exist and be a directory

Operations require matching path types - fs.read_text() takes a ReadPath, fs.write_text() takes a WritePath, fs.list_dir() takes a DirPath, and so on.

Operations

Function	Signature	Description
fs.read_text(p)	(ReadPath) -> Result[Str, FsError]	Read file as string
fs.write_text(p, s)	(WritePath, Str) -> Result[None, FsError]	Write string to file
fs.append_text(p, s)	(AppendPath, Str) -> Result[None, FsError]	Append string to file
fs.read_lines(p)	(ReadPath) -> Result[List[Str], FsError]	Read file as list of lines
fs.mkdir(p)	(Path) -> Result[DirPath, FsError]	Create directory
fs.makedirs(p)	(Path) -> Result[DirPath, FsError]	Create directory tree
fs.remove(p)	(WritePath) -> Result[None, FsError]	Delete file
fs.copy(src, dst)	(ReadPath, WritePath) -> Result[None, FsError]	Copy file
fs.move(src, dst)	(WritePath, WritePath) -> Result[None, FsError]	Move file
fs.list_dir(p)	(DirPath) -> Result[List[Str], FsError]	List directory contents
fs.walk(p)	(DirPath) -> Result[List[Str], FsError]	Recursive directory listing
fs.exists(p)	(Path) -> Bool	Check if path exists
fs.copy_dir(src, dst)	(Path, Path) -> Result[None, FsError]	Recursively copy directory tree
fs.remove_dir(p)	(Path) -> Result[None, FsError]	Recursively delete directory and contents
fs.ensure_dir(p)	(Path) -> Result[DirPath, FsError]	Create directory if it does not exist
fs.glob(pattern, base)	(Str, Str) -> Result[List[Str], FsError]	Find files matching glob pattern
fs.metadata(p)	(Path) -> Result[FsMetadata, FsError]	Get file metadata (size, timestamps, type)
fs.permissions(p)	(Path) -> Result[FsPermissions, FsError]	Get file permissions
fs.is_file(p)	(Path) -> Bool	Check if path is a regular file
fs.is_dir(p)	(Path) -> Bool	Check if path is a directory
fs.is_symlink(p)	(Path) -> Bool	Check if path is a symbolic link
fs.file_size(p)	(Path) -> Result[Int, FsError]	Get file size in bytes
fs.modified_time(p)	(Path) -> Result[Int, FsError]	Get last modified time as epoch ms
fs.walk_dir(p)	(DirPath) -> Result[List[Str], FsError]	Recursively list all paths in directory
fs.walk_files(p, ext)	(DirPath, Str) -> Result[List[Str], FsError]	Recursively find files with given extension

FsMetadata

fs.metadata(p) returns an FsMetadata object with the following methods:

Method	Returns	Description
.size()	Int	File size in bytes
.is_file()	Bool	True if path is a regular file
.is_dir()	Bool	True if path is a directory
.is_symlink()	Bool	True if path is a symbolic link
.modified_millis()	Int	Last modified time as epoch milliseconds

FsPermissions

fs.permissions(p) returns an FsPermissions object with the following methods:

Method	Returns	Description
.readable()	Bool	True if path is readable
.writable()	Bool	True if path is writable
.executable()	Bool	True if path is executable

Quick-start example

import fs

let rp = fs.read_path("input.txt").unwrap()
let content = fs.read_text(rp).unwrap()

let wp = fs.write_path("output.txt").unwrap()
fs.write_text(wp, content).unwrap()

if fs.exists(fs.path("output.txt")) {
    print("written")
}