files module¶

Directory ¶

Metadata for a directory, False for a non-directory path, None if absent.

Commands:

! (test -e <path> || test -L <path> ) || ( stat -c 'user=%U group=%G mode=%A atime=%X mtime=%Y ctime=%Z size=%s %N' <path> 2> /dev/null || stat -f 'user=%Su group=%Sg mode=%Sp atime=%a mtime=%m ctime=%c size=%z %N%SY' <path> || ls -ld <path> )

Returns:

dict[str, Any] | Literal[False] | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_directory.py.

DirectoryEntries ¶

One directory's immediate entries with their types, never recursive.

**Commands:**

```bash
find <path> -mindepth 1 -maxdepth 1 -printf '%f     %y

' || true **Returns:**python list[DirectoryEntry] ```

**Raises:**

```python
HostConnectionError
```

Examples:
    Examples can be found in ``examples/modules/files/files_directory_entries.py``.

DirectoryEntry ¶

Attributes:

Name	Type	Description
`name`		The entry's basename (no directory component); join it with the listed path to address the entry.
`type`		The entry's path type as a word -- "file", "directory", "link", "socket", "fifo", "block" or "character" -- the same vocabulary the File family's type flags use.

File ¶

Metadata for a regular file, False for a non-file path, None if absent.

Commands:

! (test -e <path> || test -L <path> ) || ( stat -c 'user=%U group=%G mode=%A atime=%X mtime=%Y ctime=%Z size=%s %N' <path> 2> /dev/null || stat -f 'user=%Su group=%Sg mode=%Sp atime=%a mtime=%m ctime=%c size=%z %N%SY' <path> || ls -ld <path> )

Returns:

dict[str, Any] | Literal[False] | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_file.py.

FileContents ¶

The text content of a file on the remote host, or None when absent.

Commands:

test -e <path> && { printf '#reemote-filecontents\n'; cat -- <path>; }

Returns:

str | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_edit.py.

FileExists ¶

Whether a regular file exists at the path.

Commands:

test -e <path> && echo yes

Returns:

bool

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_file.py.

FileFlags ¶

The ext2-family attribute flags set on a path, empty or absent alike.

Commands:

! test -e <path> || lsattr -d <path> 2> /dev/null

Returns:

list[str]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_flags.py.

FileLink ¶

The target of a symlink, or None if the link does not exist.

Commands:

readlink <path>

Returns:

str | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_link.py.

FindDirectories ¶

Paths of the directories under a start path, recursively via find.

Commands:

find <path> -type d [filters] || true

Returns:

list[str]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_find_directories.py.

FindFiles ¶

Paths of the regular files under a start path, recursively via find.

Commands:

find <path> -type f [filters] || true

Returns:

list[str]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_find_files.py.

FindFilesInfo ¶

Regular files under a start path with per-hit metadata, via find -printf.

**Commands:**

```bash
find <path> -type f [filters] -printf '%p   %s      %m      %u      %g      %T@

' || true **Returns:**python list[FoundFile] ```

**Raises:**

```python
HostConnectionError
```

Examples:
    Examples can be found in ``examples/modules/files/files_find_files_info.py``.

FindInFile ¶

Lines of a file matching a grep pattern; [] if none, None if absent.

Commands:

grep -e <pattern> <path> 2> /dev/null || ( find <path> -type f > /dev/null && echo __reemote_exists_<path> || true )

Returns:

list[str] | None

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_find_in_file.py.

FindLinks ¶

Paths of the symlinks under a start path, recursively via find.

Commands:

find <path> -type l [filters] || true

Returns:

list[str]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_find_links.py.

FoundFile ¶

Attributes:

Name	Type	Description
`path`		The file's path exactly as find printed it (the start path's spelling carried through, relative if the start was relative).
`size`		The file's size in bytes.
`mode`		The octal-looking permission int (644, 4755, ...), including the setuid/setgid/sticky bits -- the same convention as File.
`user`		The owning user's name (find prints the numeric uid when the name cannot be resolved).
`group`		The owning group's name (numeric gid when unresolvable).
`mtime`		The last-modification time as a naive UTC datetime at whole-second precision (the File convention), or None when find printed no parseable timestamp.

Link ¶

Metadata for a symlink plus its target, False for non-link, None if absent.

Commands:

! (test -e <path> || test -L <path> ) || ( stat -c 'user=%U group=%G mode=%A atime=%X mtime=%Y ctime=%Z size=%s %N' <path> 2> /dev/null || stat -f 'user=%Su group=%Sg mode=%Sp atime=%a mtime=%m ctime=%c size=%z %N%SY' <path> || ls -ld <path> )

Returns:

dict[str, Any] | Literal[False] | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_link.py.

Md5File ¶

The md5 hex digest of a file on the remote host, or None if absent.

Commands:

test -e <path> && ( md5sum < <path> 2> /dev/null || md5 < <path> 2> /dev/null ) || true

Returns:

str | None

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_md5.py.

RemoteFileSha1 ¶

The sha1 hex digest of a file on the remote host, or None if absent.

Commands:

sha1sum <path>

Returns:

str | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_put.py and examples/modules/files/files_get.py.

SameFile ¶

Whether two paths name one and the same file (a hard link pair).

Commands:

test <path> -ef <target> && echo true || echo false

Returns:

bool

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_same_file.py.

Sha256File ¶

The sha256 hex digest of a file on the remote host, or None if absent.

Commands:

test -e <path> && ( sha256sum < <path> 2> /dev/null || shasum -a 256 < <path> 2> /dev/null || sha256 < <path> 2> /dev/null ) || true

Returns:

str | None

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_sha256.py.

Sha384File ¶

The sha384 hex digest of a file on the remote host, or None if absent.

Commands:

test -e <path> && ( sha384sum < <path> 2> /dev/null || shasum -a 384 < <path> 2> /dev/null || sha384 < <path> 2> /dev/null ) || true

Returns:

str | None

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_sha384.py.

Socket ¶

Metadata for a socket, False for a non-socket path, None if absent.

Commands:

! (test -e <path> || test -L <path> ) || ( stat -c 'user=%U group=%G mode=%A atime=%X mtime=%Y ctime=%Z size=%s %N' <path> 2> /dev/null || stat -f 'user=%Su group=%Sg mode=%Sp atime=%a mtime=%m ctime=%c size=%z %N%SY' <path> || ls -ld <path> )

Returns:

dict[str, Any] | Literal[False] | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_socket.py.

copy `async` ¶

copy(
    ctx: OpContext,
    src: str,
    dest: str,
    overwrite: bool = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Copy a remote file/directory into a remote directory.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`src`	`str`	The remote path to copy.	required
`dest`	`str`	The remote directory to copy `src` into; the copied path becomes `dest/basename(src)` and the source stays in place.	required
`overwrite`	`bool`	When the destination path already exists, force the copy (`cp -r -f`) instead of comparing or raising. Defaults to False.	`False`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The copy command, when a copy is needed.

Raises:

CommandNotFoundError, HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/files/files_copy.py.

directory `async` ¶

directory(
    ctx: OpContext,
    path: str,
    present: bool = True,
    user: str | None = None,
    group: str | None = None,
    mode: int | str | None = None,
    recursive: bool = False,
    force: bool = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add, update or remove a directory.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`path`	`str`	The remote directory path to manage.	required
`present`	`bool`	Whether the directory should exist. Defaults to True.	`True`
`user`	`str \| None`	The user to own the directory. Defaults to None.	`None`
`group`	`str \| None`	The group to own the directory. Defaults to None.	`None`
`mode`	`int \| str \| None`	The directory's permissions -- an octal-digit int or string (`750`, `"0750"`, `"0o750"`) or a symbolic mode. Defaults to None.	`None`
`recursive`	`bool`	Whether to apply `mode`, `user` and `group` recursively to the directory's contents. Defaults to False.	`False`
`force`	`bool`	Replace an existing non-directory at `path` (`rm -rf`) instead of raising. Defaults to False.	`False`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The directory commands, only when the directory differs from the request.

Raises:

CommandNotFoundError, HostConnectionError, TypeError, ValueError

Examples:

Examples can be found in examples/modules/files/files_op_directory.py.

edit `async` ¶

edit(
    ctx: OpContext,
    path: str,
    transform: Callable[[str | None], str],
) -> AsyncGenerator[Command]

Edit a remote file through a pure content transform.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`path`	`str`	The remote file to edit.	required
`transform`	`Callable[[str \| None], str]`	A pure, idempotent callable taking the current content (`str`, or `None` when the file is absent) and returning the desired content as a `str`.	required

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The rewrite upload, when the transformed content differs.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/files/files_edit.py.

file `async` ¶

file(
    ctx: OpContext,
    path: str,
    present: bool = True,
    user: str | None = None,
    group: str | None = None,
    mode: int | str | None = None,
    touch: bool = False,
    create_remote_dir: bool = True,
    force: bool = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add, update or remove a regular file.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`path`	`str`	The remote file path to manage.	required
`present`	`bool`	Whether the file should exist. Defaults to True.	`True`
`user`	`str \| None`	The user to own the file. Defaults to None.	`None`
`group`	`str \| None`	The group to own the file. Defaults to None.	`None`
`mode`	`int \| str \| None`	The file's permissions -- an octal-digit int or string (`750`, `"0750"`, `"0o750"`) or a symbolic mode. Defaults to None.	`None`
`touch`	`bool`	Whether to `touch` an existing file. The option is not idempotent: the `touch` always re-runs. Defaults to False.	`False`
`create_remote_dir`	`bool`	Whether to `mkdir -p` the file's parent directory when it is missing. Defaults to True.	`True`
`force`	`bool`	Replace an existing non-file at `path` (`rm -rf`) instead of raising. Defaults to False.	`False`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The file commands, only when the file differs from the request.

Raises:

CommandNotFoundError, HostConnectionError, TypeError, ValueError

Examples:

Examples can be found in examples/modules/files/files_op_file.py.

flags `async` ¶

flags(
    ctx: OpContext,
    path: str,
    flags: str | list[str] | tuple[str, ...] | None = None,
    present: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Set or clear a path's ext2-family attribute flags.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`path`	`str`	The remote path whose attribute flags to manage.	required
`flags`	`str \| list[str] \| tuple[str, ...] \| None`	The one-letter ext2 attribute flags to set or clear (`"i"` immutable, `"a"` append-only, ...); a bare string names one flag. Prefer a tuple when building requests via `op()`, because request arguments must stay hashable. Defaults to None.	`None`
`present`	`bool`	Whether the flags should be set (`True`) or cleared (`False`). Defaults to True.	`True`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The `chattr` command, only when some requested flag differs from the current set.

Raises:

CommandNotFoundError, HostConnectionError, TypeError, ValueError

Examples:

Examples can be found in examples/modules/files/files_flags.py.

get `async` ¶

get(
    ctx: OpContext, src: str, dest: IO[Any]
) -> AsyncGenerator[Command]

Download a remote file into an IO-like destination.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`src`	`str`	The remote path to download.	required
`dest`	`IO[Any]`	The seekable, writable IO-like destination on the control machine.	required

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The download transfer, when the content differs.

Raises:

CommandNotFoundError, HostConnectionError, OSError

Examples:

Examples can be found in examples/modules/files/files_get.py.

install `async` ¶

install(
    ctx: OpContext,
    content: str,
    dest: str,
    mode: str = "0644",
    user: str | None = None,
    group: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Install text content at a root-owned path via spool-and-install.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`content`	`str`	The desired text content of the file.	required
`dest`	`str`	The remote path to install the content at.	required
`mode`	`str`	The installed file's permissions as octal-digit text (`"0644"`, `"600"`). Defaults to "0644".	`'0644'`
`user`	`str \| None`	The user to own the installed file. Defaults to None (root, the elevated install's owner).	`None`
`group`	`str \| None`	The group to own the installed file. Defaults to None (root).	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The spool transfer and the elevated install command, only when the content differs.

Raises:

CommandNotFoundError, HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/files/files_install.py.

link `async` ¶

link(
    ctx: OpContext,
    path: str,
    target: str | None = None,
    present: bool = True,
    user: str | None = None,
    group: str | None = None,
    symbolic: bool = True,
    create_remote_dir: bool = True,
    force: bool = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add, update or remove a link.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`path`	`str`	The path of the link to manage.	required
`target`	`str \| None`	The path the link points to. Required when `present` is True. Defaults to None.	`None`
`present`	`bool`	Whether the link should exist. Defaults to True.	`True`
`user`	`str \| None`	The user to own the link. Defaults to None.	`None`
`group`	`str \| None`	The group to own the link. Defaults to None.	`None`
`symbolic`	`bool`	Whether to make a symbolic link rather than a hard link. Defaults to True.	`True`
`create_remote_dir`	`bool`	Whether to `mkdir -p` the link's parent directory when it is missing. Defaults to True.	`True`
`force`	`bool`	Replace an existing non-link at `path` (`rm -rf`) instead of raising. Defaults to False.	`False`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The link commands, only when the link differs from the request.

Raises:

CommandNotFoundError, HostConnectionError, TypeError, ValueError

Examples:

Examples can be found in examples/modules/files/files_op_link.py.

move `async` ¶

move(
    ctx: OpContext,
    src: str,
    dest: str,
    overwrite: bool = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Move a remote file/directory/link into a remote directory.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`src`	`str`	The remote path to move.	required
`dest`	`str`	The remote directory to move `src` into; the moved path becomes `dest/basename(src)`.	required
`overwrite`	`bool`	When the destination path already exists, remove it first (`rm -rf`) instead of raising. Defaults to False.	`False`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The move command, always, preceded by a removal when `overwrite` clears an existing target.

Raises:

CommandNotFoundError, HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/files/files_move.py.

put `async` ¶

put(
    ctx: OpContext, src: IO[Any], dest: str
) -> AsyncGenerator[Command]

Upload an IO-like source to a remote path.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`src`	`IO[Any]`	The seekable IO-like source on the control machine.	required
`dest`	`str`	The remote path to write.	required

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The upload transfer, when the content differs.

Raises:

CommandNotFoundError, HostConnectionError, OSError

Examples:

Examples can be found in examples/modules/files/files_put.py.

files module¶

Directory ¶

DirectoryEntries ¶

DirectoryEntry ¶

File ¶

FileContents ¶

FileExists ¶

FileFlags ¶

FileLink ¶

FindDirectories ¶

FindFiles ¶

FindFilesInfo ¶

FindInFile ¶

FindLinks ¶

FoundFile ¶

Link ¶

Md5File ¶

RemoteFileSha1 ¶

SameFile ¶

Sha256File ¶

Sha384File ¶

Socket ¶

copy async ¶

directory async ¶

edit async ¶

file async ¶

flags async ¶

get async ¶

install async ¶

link async ¶

move async ¶

put async ¶

copy `async` ¶

directory `async` ¶

edit `async` ¶

file `async` ¶

flags `async` ¶

get `async` ¶

install `async` ¶

link `async` ¶

move `async` ¶

put `async` ¶