nodestep.workspace

Files for agents, on the local disk or in memory.

LocalWorkspace and InMemoryWorkspace implement Workspace and refuse paths that leave their root. See Workspace and memory.

Interface

Workspace

Files an agent can read and change, confined to a root.

Attributes

root_dir

Path

Absolute root directory of the workspace.

Methods

resolve_path(path)

Resolve a path inside the workspace.

resolve_path(path) -> tuple[Path, str]

Parameters

path

str | None

Path relative to the root; None or "." is the root.

Returns

tuple[Path, str]

Absolute path and normalized relative path.

Raises

PathAccessError

If the path leaves the workspace root or breaks a rule of nodestep.workspace.paths.check_path.

read_file(path)

Read a text file.

read_file(path) -> str

Parameters

path

str

Path relative to the workspace root.

write_file(path, content)

Write a text file, creating parent directories.

write_file(path, content) -> None

Parameters

path	str	Path relative to the workspace root.
content	str

list_dir(path)

List a directory; subdirectories end with /.

list_dir(path='.') -> list[str]

Parameters

path

str

Path relative to the workspace root.

Returns

list[str]

Sorted entry names.

Raises

FileNotFoundError	If the path does not exist.
NotADirectoryError	If the path is a file.

exists(path)

Whether a file or directory exists.

exists(path) -> bool

Parameters

path

str

Path relative to the workspace root.

delete(path)

Delete a file or directory.

delete(path) -> bool

Parameters

path

str

Path relative to the workspace root.

Returns

bool	Whether something was deleted.

edit(path, old, new, ...)

Replace text in a file.

edit(path, old, new, *, replace_all=False) -> int

Parameters

path	str	Path relative to the workspace root.
old	str	Text to find.
new	str	Its replacement.
replace_all	bool	Replace every occurrence instead of the first.

Returns

int	Number of replacements.

Raises

ValueError

If old is empty.

glob(pattern, path)

List files matching a glob pattern.

glob(pattern, path='.') -> list[str]

Parameters

pattern	str	Pattern such as "src/**/*.py"; it may not leave the root.
path	str	Directory to search from.

Returns

list[str]

Matching paths relative to the root.

Raises

FileNotFoundError

If path does not exist.

grep(pattern, path, ...)

Find lines matching a regular expression.

grep(pattern, path='.', *, glob_pattern=None) -> GrepResult

Parameters

pattern	str	Regular expression.
path	str	File or directory to search.
glob_pattern	str | None	Only search the files of a directory path that match this pattern; a file path is searched whatever the pattern.

Returns

GrepResult

Matching lines keyed by relative path, and the relative paths of files skipped because they are too large, not UTF-8 text, not readable, or symlinks that point outside the root.

Raises

FileNotFoundError

If path does not exist.

GrepResult

GrepResult(*, matches={}, skipped=[])

Matching lines by relative path, and the files that could not be read.

Attributes

matches	dict[str, list[str]]	Matching lines, keyed by the file's path relative to the root.
skipped	list[str]	Relative paths of files that are too large, not UTF-8 text, not readable, or symlinks that point outside the root.