nodestep.workspace.integrations.local

LocalWorkspace, which keeps an agent's files in a folder on disk.

See Workspaces.

LocalWorkspace

LocalWorkspace(root_dir, *, create=False, max_file_read_bytes=256000)

Workspace backed by a directory on disk.

Subclass of Workspace.

Paths, globs and symlinks cannot reach outside the root, and paths follow the rules of check_path listed in Workspaces.

Parameters

root_dir	str | Path	Root directory.
create	bool	Create root_dir and its parents if missing; otherwise a missing root raises.
max_file_read_bytes	int	Largest file read_file accepts.

Raises

WorkspaceError

If root_dir is missing and create is false, or is not a directory.

Attributes

root_dir

Path

Absolute root directory.

Methods

resolve_path(path)

Resolve a path inside the root, following symlinks.

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 resolved path and the relative path with / separators.

Raises

PathAccessError

If the path, or a symlink target in it, leaves the root, or the path fails check_path.

read_file(path)

Read a UTF-8 text file, keeping its line endings.

read_file(path) -> str

Parameters

path

str

Path relative to the workspace root.

Raises

FileNotFoundError	If the file does not exist.
WorkspaceError	If the file is larger than max_file_read_bytes or not UTF-8 text.
PathAccessError	If the path leaves the root or fails check_path.

write_file(path, content)

Write a UTF-8 text file as given, creating parent directories.

write_file(path, content) -> None

Parameters

path	str	Path relative to the workspace root.
content	str

Raises

IsADirectoryError	If the path is a directory.
PathAccessError	If the path leaves the root or fails check_path.

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.
PathAccessError	If the path leaves the root or fails check_path.

exists(path)

Whether a file or directory exists.

exists(path) -> bool

Parameters

path

str

Path relative to the workspace root.

Raises

PathAccessError

If the path leaves the root or fails check_path.

delete(path)

Delete a file, directory or symlink (never its target).

delete(path) -> bool

Parameters

path

str

Path relative to the workspace root.

Returns

bool	Whether something was deleted.

Raises

WorkspaceError	If path is the workspace root.
PathAccessError	If the path leaves the root or fails check_path.

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

Replace text in a file, keeping its line endings.

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

In a CRLF file, old and new written with LF match and are written with CRLF.

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.
FileNotFoundError	If the file does not exist.
WorkspaceError	If the file is larger than max_file_read_bytes or not UTF-8 text.
PathAccessError	If the path leaves the root or fails check_path.

glob(pattern, path)

List files matching a glob pattern, without symlinks leaving the root.

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

Parameters

pattern	str	Pattern such as "src/**/*.py", relative to path.
path	str	Directory to search from, relative to the root.

Returns

list[str]

Sorted matching file paths relative to the root.

Raises

FileNotFoundError	If path does not exist.
PathAccessError	If pattern names a drive, is absolute or contains .., or path leaves the root or fails check_path.

grep(pattern, path, ...)

Find lines matching a regular expression inside the root.

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

Parameters

pattern	str	Regular expression, searched in each line.
path	str	File or directory to search, relative to the root.
glob_pattern	str | None	Only search the files of a directory path that match it; a file path is always searched.

Returns

GrepResult

Matching lines by relative path, and in skipped the files that are larger than max_file_read_bytes, not UTF-8 text, not readable, or symlinks that point outside the root.

Raises

FileNotFoundError	If path does not exist.
error	If pattern is not a valid regular expression.
PathAccessError	If glob_pattern names a drive, is absolute or contains .., or path leaves the root or fails check_path.