nodestep.workspace.integrations.virtual

InMemoryWorkspace, which keeps an agent's files in memory.

See Workspaces.

InMemoryWorkspace

Workspace kept in memory, with the same rules as LocalWorkspace.

Subclass of Workspace.

Attributes

root_dir

Path

Not available; the workspace has no directory on disk.

Methods

resolve_path(path)

Normalize a path, refusing anything outside the root.

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

Parameters

path

str | None

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

Returns

tuple[Path, str]

The path under the placeholder root /virtual and the normalized relative path.

Raises

PathAccessError

If the path leaves the root or fails check_path.

read_file(path)

Read a file.

read_file(path) -> str

Parameters

path

str

Path relative to the workspace root.

Raises

FileNotFoundError	If the file does not exist.
IsADirectoryError	If the path is a directory.
PathAccessError	If the path leaves the root or fails check_path.

write_file(path, content)

Write a file; parent directories exist as soon as a file is in them.

write_file(path, content) -> None

Parameters

path	str	Path relative to the workspace root.
content	str

Raises

IsADirectoryError	If the path is a directory.
FileExistsError	If a parent of the path is a file.
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 or directory; the root cannot be deleted.

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

glob(pattern, path)

List files matching a glob pattern.

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.

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; skipped is always empty.

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.