FileSystem

Paths refer to the target filesystem. glob does not guarantee result order; sort the returned list when order matters. read_str uses the target Python process’s default text encoding.

class rmote.tools.fs.FileSystem

Bases: Tool

Remote filesystem operations - read, glob, and idempotent line-in-file.

Example using disposable files (the same methods can be called remotely):

>>> from tempfile import TemporaryDirectory
>>> with TemporaryDirectory() as directory:
...     path = str(Path(directory) / "app.conf")
...     print(FileSystem.write(path, "enabled=no\n"))
...     print(FileSystem.write(path, "enabled=no\n"))
...     diff = FileSystem.line_in_file(path, line="enabled=yes", regexp="^enabled=")
...     print(bool(diff), FileSystem.read_str(path).strip())
...     print(FileSystem.line_in_file(path, line="enabled=yes", regexp="^enabled="))
...     print(FileSystem.stat(path).is_file)
...     print(FileSystem.absent(path), FileSystem.absent(path))
True
False
True enabled=yes

True
True False

static absent(path, *, recursive=False)

Remove path if it exists.

Parameters:

• path (Text) – Path to remove.

• recursive (bool) – If True, remove directories and their contents recursively (equivalent to rm -rf). If False (default), non-empty directories raise OSError.

Return type:

bool

Returns:

True if path existed and was removed, False if it was already absent.

static directory(path, *, mode=493, owner=None, group=None)

Ensure a directory exists at path with the given permissions.

Creates the directory (and any missing parents) if absent. If it already exists, applies mode, owner, and group if they differ.

Parameters:

• path (Text) – Target directory path.

• mode (getint) – Directory permission bits (default 0o755).

• owner (Text | None) – Owner username; None leaves ownership unchanged.

• group (Text | None) – Group name; None leaves group unchanged.

Return type:

bool

Returns:

True if the directory was created or its attributes changed.

static glob(path, pattern)

Return all paths under path that match pattern.

Parameters:

• path (Text | Path) – Directory to search in.

• pattern (Text) – Glob pattern relative to path (e.g. "*.conf").

Return type:

list[Text]

Returns:

Matching paths as strings, with no guaranteed order.

static line_in_file(path, *, line, regexp=None, strip=True, create=False, match=LineInFileMatch.FIRST)

Ensure line is present in the file at path, idempotently.

If regexp is given, replace the first (or all, with match=ALL) lines that match the pattern with line. If no pattern matches, append line only when it is absent. Without regexp, append line only when it is absent.

Parameters:

• path (Text) – Path to the file to modify.

• line (Text) – The desired line content to insert or substitute.

• regexp (Text | None) – A regex pattern to match against existing lines. When a match is found, the matching line(s) are replaced with line.

• strip (bool) – Compare lines after stripping whitespace when looking for an exact match, including when regexp has no matches. Default True.

• create (bool) – Create the file if it does not exist. Default False.

• match (LineInFileMatch) – Whether to replace the FIRST matching line or ALL matching lines.

Return type:

Text

Returns:

A unified diff string describing the change, or an empty string if the file was already in the desired state.

Raises:

FileNotFoundError – If path does not exist and create is False.

static read_bytes(path)

Read path and return its raw contents.

Parameters:

path (Text) – Absolute or relative path on the remote filesystem.

Return type:

bytes

Returns:

File contents as bytes.

static read_str(path)

Read path using the remote Python process’s default text encoding.

Parameters:

path (Text) – Absolute or relative path on the remote filesystem.

Return type:

Text

Returns:

File contents as str.

static stat(path)

Return metadata for path without following symlinks.

Parameters:

path (Text) – Path to inspect.

Return type:

StatResult

Returns:

StatResult with file metadata. If path does not exist, returns a StatResult with exists=False and all numeric fields set to zero.

static symlink(path, target)

Ensure path is a symlink pointing to target.

If path already exists as the correct symlink, this is a no-op. If it exists as a wrong symlink or a regular file, it is replaced.

Parameters:

• path (Text) – Path where the symlink should be created.

• target (Text) – The target the symlink should point to.

Return type:

bool

Returns:

True if the symlink was created or updated.

static write(path, content, *, mode=420, owner=None, group=None)

Write content to path idempotently.

All of content, mode, owner, and group are compared to the current state. Returns True if any of them differed and the file was updated.

Parameters:

• path (Text) – Destination path on the remote filesystem.

• content (Text | bytes) – File content as a string (UTF-8) or bytes.

• mode (getint) – File permission bits (default 0o644).

• owner (Text | None) – Owner username; None leaves ownership unchanged.

• group (Text | None) – Group name; None leaves group unchanged.

Return type:

bool

Returns:

True if the file was created or updated, False if already in the desired state.

Types

class rmote.tools.fs.LineInFileMatch(*values)

Bases: IntEnum

Controls how regexp matches are replaced by FileSystem.line_in_file().

FIRST

Replace only the first line that matches the regexp.

ALL

Replace every line that matches the regexp.