`fs`¶

High-Level file manipulation.

Module Contents¶

Functions¶

`walk_tree`(→ collections.abc.Generator[tuple[str, ...)	Copy of the Python implementation of walk that returns DirEntry.
`cp`(→ None)	Copy files.
`directory_content`(→ list[str])	Return the complete directory content (recursively).
`echo_to_file`(→ None)	Output content into a file.
`find`(→ list[str])	Find files or directory recursively.
`find_paths`(→ list[pathlib.Path])	Find files or directory recursively.
`get_filetree_state`(→ str)	Compute a hash on a filetree to reflect its current state.
`ls`(→ list[str])	List files.
`ls_paths`(→ list[pathlib.Path])	List files.
`mkdir`(→ None)	Create a directory.
`mv`(→ None)	Move files.
`rm`(→ None)	Remove files.
`splitall`(→ tuple[str, Ellipsis])	Split a path into a list of path components.
`sync_tree`(→ tuple[list[str], list[str]])	Synchronize the files and directories between two directories.
`extension`(→ str)	Return the extension of a given filename.

Attributes¶

`logger`
`WSL_SYMLINK_TAG`
`TIMESTAMP_TOLERANCE`
`FICLONE`
`FICLONE_MINIMAL_KERNEL_VERSION`
`SENDFILE_MAX_CHUNK`
`SENDFILE_MIN_CHUNK`
`WINDOWS_RESERVED_FILENAMES`
`WINDOWS_EPOCH`
`WINDOWS_BUFFER_SIZE`
`VCS_IGNORE_LIST`
`SYNC_BREAK`
`SYNC_MKDIR`
`SYNC_RM`
`SYNC_COPY`

fs.logger¶

fs.WSL_SYMLINK_TAG = 2684354589¶

fs.TIMESTAMP_TOLERANCE = 0.001¶

fs.FICLONE = 1074041865¶

fs.FICLONE_MINIMAL_KERNEL_VERSION = 5¶

fs.SENDFILE_MAX_CHUNK = 2147479552¶

fs.SENDFILE_MIN_CHUNK¶

fs.WINDOWS_RESERVED_FILENAMES¶

fs.WINDOWS_EPOCH = 11644473600¶

fs.WINDOWS_BUFFER_SIZE¶

exception fs.FSError(message: str | list[str], origin: str | None = None)¶

Bases: e3.error.E3Error

Exception raised for file system operations errors.

fs.walk_tree(path: str | pathlib.Path, *, topdown: bool = True, follow_symlinks: bool = False) → collections.abc.Generator[tuple[str, list[os.DirEntry], list[os.DirEntry]]]¶

Copy of the Python implementation of walk that returns DirEntry.

The main advantage of DirEntry is that on Windows it contains both the path and the stat information which on Windows can save a significant amount of time as both information are returned by the API in one call.

See os.walk documentation

fs.cp(source: str | pathlib.Path, target: str | pathlib.Path, copy_attrs: bool = True, recursive: bool = False, preserve_symlinks: bool = False) → None¶

Copy files.

Parameters:

source – a glob pattern
target – target file or directory. If the source resolves as several files then target should be a directory
copy_attrs – If True, also copy all the file attributes such as mode, timestamps, ownership, etc.
recursive – If True, recursive copy. This also preserves attributes; if copy_attrs is False, a warning is emitted.
preserve_symlinks – if True symlinks are recreated in the destination folder

Raises:

FSError – if an error occurs

fs.directory_content(path: str | pathlib.Path, include_root_dir: bool = False, unixpath: bool = False) → list[str]¶

Return the complete directory content (recursively).

Parameters:

path – path for the which the content should be returned
include_root_dir – if True include the root directory in the paths returned by the function. Otherwise return relative paths
unixpath – if True return unix compatible paths (calling unixpath on all elements returned

Returns:

a list of of path. Note that directories will end with a path separator

fs.echo_to_file(filename: str | pathlib.Path, content: str | list[str], append: bool = False) → None¶

Output content into a file.

This function is useful when writing few content to a file for which we don’t want to keep a file descriptor opened . In other cases, it’s more efficient to open a file and use the regular python I/O functions.

Parameters:

filename – file to write into
content – string to be written
append – if True append to the file, otherwise overwrite.

fs.find(root: str | pathlib.Path, pattern: str | None = None, include_dirs: bool = False, include_files: bool = True, follow_symlinks: bool = False) → list[str]¶

Find files or directory recursively.

Parameters:

root – directory from which the research start
pattern – glob pattern that files or directories should match in order to be included in the final result
include_dirs – if True include directories
include_files – if True include regular files
follow_symlinks – if True include symbolic links

Returns:

a list of files

fs.find_paths(root: str | pathlib.Path, pattern: str | None = None, include_dirs: bool = False, include_files: bool = True, follow_symlinks: bool = False) → list[pathlib.Path]¶

Find files or directory recursively.

Parameters:

root – directory from which the research start
pattern – glob pattern that files or directories should match in order to be included in the final result
include_dirs – if True include directories
include_files – if True include regular files
follow_symlinks – if True include symbolic links

Returns:

a list of Path objects

fs.get_filetree_state(path: str | pathlib.Path, ignore_hidden: bool = True, hash_content: bool = False) → str¶

Compute a hash on a filetree to reflect its current state.

Parameters:

path – root path of the file tree to be checked
ignore_hidden – if True (default) then files and directories tarting with a dot are ignored.
hash_content – if True, include the content in the hash.

Returns:

a hash as a string

By default, the function will not report changes in the hash if a file is modified and its attributes (size, modification time and mode) are not changed. This case is quite uncommon. By ignoring it we can compute efficiently a hash representing the state of the file tree without having to read the content of all files.

fs.ls(path: str | pathlib.Path | collections.abc.Iterable[str | pathlib.Path], emit_log_record: bool = True) → list[str]¶

List files.

Parameters:

path – glob pattern or glob pattern list
emit_log_record – if True, emit a log (debug) record

Returns:

a list of filenames

This function do not raise an error if no file matching the glob pattern is encountered. The only consequence is that an empty list is returned.

fs.ls_paths(path: str | pathlib.Path | collections.abc.Iterable[str | pathlib.Path], emit_log_record: bool = True) → list[pathlib.Path]¶

List files.

Parameters:

path – glob pattern or glob pattern list
emit_log_record – if True, emit a log (debug) record

Returns:

a list of Path objects

This function do not raise an error if no file matching the glob pattern is encountered. The only consequence is that an empty list is returned.

fs.mkdir(path: str | pathlib.Path, mode: int = 493, quiet: bool = False) → None¶

Create a directory.

Parameters:

path – path to create. If intermediate directories do not exist the procedure create them
mode – default is 0755
quiet – whether a log record should be emitted when creating the directory

Raises:

FSError – if an error occurs

This function behaves quite like mkdir -p command shell. So if the directory already exist no error is raised.

fs.mv(source: str | pathlib.Path | collections.abc.Iterable[str] | collections.abc.Iterable[pathlib.Path], target: str | pathlib.Path) → None¶

Move files.

Parameters:

source – a glob pattern, a sequence/iterator of glob patterns, a path, or a sequence/iterator of paths
target – target file or directory. If the source resolves as several files then target should be a directory

Raises:

FSError – if an error occurs

fs.rm(path: str | pathlib.Path | collections.abc.Iterable[str] | collections.abc.Iterable[pathlib.Path], recursive: bool = False, glob: bool = True) → None¶

Remove files.

Parameters:

path – a glob pattern, a sequence/iterator of glob patterns, a path, or a sequence/iterator of paths
recursive – if True do a recursive deletion. Default is False
glob – if True globbing pattern expansion is used

Raises:

FSError – if an error occurs

Note that the function will not raise an error is there are no file to delete.

fs.splitall(path: str | pathlib.Path) → tuple[str, Ellipsis]¶

Split a path into a list of path components.

Parameters:: path – path to split
Returns:: a list of path components

fs.VCS_IGNORE_LIST = ('RCS', 'SCCS', 'CVS', 'CVS.adm', 'RCSLOG', '.svn', '.git', '.hg', '.bzr', '.cvsignore',...¶

fs.SYNC_BREAK = 0¶

fs.SYNC_MKDIR = 1¶

fs.SYNC_RM = 2¶

fs.SYNC_COPY = 3¶

fs.sync_tree(source: str | pathlib.Path, target: str | pathlib.Path, ignore: str | collections.abc.Sequence[str] | None = None, file_list: list[str] | None = None, delete: bool = True, preserve_timestamps: bool = True, delete_ignore: bool = False) → tuple[list[str], list[str]]¶

Synchronize the files and directories between two directories.

Parameters:

source – the directory from where the files and directories need to be copied
target – the target directory
ignore – glob pattern or list of files or directories to ignore, if the name starts with / then only the path is taken into account from the root of the source (or target) directory. If the ignore value contains a glob pattern, it is taken in account only if it doesn’t contain a /, since for now the filtering is not segmented by ‘/’.
file_list – list of files to synchronize, if empty synchronize all files. Note that if file in the list is a directory then the complete content of that directory is included. Note also that ignore list takes precedence other file_list.
delete – if True, remove files from target if they do not exist in source
preserve_timestamps – if True preserve original timestamps. If False updated files get their timestamps set to current time.
delete_ignore – if True files that are explicitly ignored are deleted. Note delete should be set to True in that case.

fs.extension(path: str | pathlib.Path) → str¶

Return the extension of a given filename.

Contrary to os.path.splitext which returns .gz, the function will return .tar.gz if the file is FILENAME.tar.gz.

Parameters:: path – a path
Returns:: an extension

fs¶

Module Contents¶

Functions¶

Attributes¶

`fs`¶