fs

High-Level file manipulation.

Module Contents

Functions

cp(→ None)

Copy files.

directory_content(→ list[str])

Return the complete directory content (recusrsively).

echo_to_file(→ None)

Output content into a file.

find(→ list[str])

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.

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

VCS_IGNORE_LIST

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

Bases: e3.error.E3Error

Exception raised by functions defined in E3.

fs.cp(source: str, target: str, 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, include_root_dir: bool = False, unixpath: bool = False) → list[str]

Return the complete directory content (recusrsively).

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, 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, 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.get_filetree_state(path: str, 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 | list[str], 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.mkdir(path: str, 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 | list[str], target: str) → None

Move files.

Parameters:

  • source – a glob pattern

  • 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 | list[str], recursive: bool = False, glob: bool = True) → None

Remove files.

Parameters:

  • path – a glob pattern, or a list of glob patterns

  • 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) → 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_tree(source: str, target: str, 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 explicitely ignored are deleted. Note delete should be set to True in that case.

fs.extension(path: str) → 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