File Handling

Pyfai strictly differentiates between virtual paths in the target system (TargetPath) and physical paths in the installer system (InstallerPath). While the former are always rooted in the target system’s filesystem root, only the latter can be resolved as pyfai is running in the installer system.

Most functions in this package work on TargetPaths. Sometimes, however, access to the actual target filesystem is required. Therefore this module provides functions to convert between both path types.

During softupdate, the installer system actually IS the target system, so in this case the value of a TargetPath to a specific file is identical to the InstallerPath to the same file, although both are still separate classes.

Since a TargetPath is only virtual and not (at least not during an install) always resolvable it is an alias to pathlib.PurePosixPath. Conversely, an InstallerPath is actually simply a path in the currently running system, so it aliases pathlib.PosixPath.

To convert between TargetPaths and InstallerPaths, use resolve() and unresolve().

fai.files.InstallerPath

Physical path in the installer system

fai.files.TargetPath

Virtual path in the target system

fai.files.chmod(path, *, mode=420, user='root', group='root')

Change mode and owner/group of a file

Parameters

  • path (PurePosixPath) – path of file to chmod

  • mode (int) – desired file mode

  • user (str) – desired file owner

  • group (str) – desired file group

Raises

FileNotFoundError – if path does not exist

This function is idempotent.

fai.files.fcopy(*args, recursively=False, user='root', group='root', mode=420, remove_backup=True, delete_orphan=True, ignore_warnings=True)

Run fcopy(8)

Parameters

  • args (Sequence[PurePosixPath]) – paths of files to install

  • recursively (bool) – enable recursive mode (-r)

  • user (str) – set file owner (-m)

  • group (str) – set file group (-m)

  • mode (int) – set file mode (-m)

  • remove_backup (bool) – remove *.pre_fcopy backup files (-B)

  • delete_orphan (bool) – delete target files when no class applies (-d)

  • ignore_warnings (bool) – ignore warnings when no class applies (-i)

fai.files.mkdir(path, *, mode=493, user='root', group='root')

Create a directory relative to target

Parameters

  • path (PurePosixPath) – path of directory to create

  • mode (int) – desired directory mode

  • user (str) – desired directory owner

  • group (str) – desired directory group

Raises

FileExistsError – if path is a non-directory file

Parent directories are created with default mode/owner/group if they do not exist.

This function is idempotent.

fai.files.resolve(target_path)

Resolve a path in the target system

Parameters

target_path (PurePosixPath) – pure path in the target system

Return type

PosixPath

Returns

absolute path in the installer system within env.target

fai.files.unresolve(installer_path)

Find the target path for a resolved path

Parameters

installer_path (PosixPath) – resolved path

Return type

PurePosixPath

Returns

absolute path in target system

Raises

ValueError – if installer_path not within env.target