doxysphinx.utils.files

The files module contains several file related helper functions.

Module Contents

Functions

write_file(file, data[, separator])	Write an array of lines to a file in one call.
replace_in_file(file, search, replacement)	Replace a text in a file.
multi_replace_in_file(file, *search_replace_pair)	Replace text inside a file. Supports multiple replacements.
multi_glob(→ List[pathlib.Path])	Evaluate multiple glob patterns at once.
copy_if_different(→ List[pathlib.Path])	Copy files with given glob patterns from source_dir to target_dir but only if the files are different.
stringify_paths(→ str)	Convert a list of paths to a bulleted string where each path is on a new line.
hash_blake2b(→ str)	Fast file hash based on blake2b hash algorithm.

doxysphinx.utils.files.write_file(file: pathlib.Path, data: Iterable[str], separator: str | None = None)

Write an array of lines to a file in one call.

Parameters:

• file – The path to the file.

• data – An array of lines to write to the file.

• separator – The line separator. Defaults to os.linesep = autodetect for current os. If you want to force a unix “lf” file use ‘n’, if you want to force a windows “crlf” file use ‘rn’., defaults to None

doxysphinx.utils.files.replace_in_file(file: pathlib.Path, search: str, replacement: str)

Replace a text in a file.

Parameters:

• file – The file to do the replacement in.

• search – The text to search inside the file.

• replacement – The replacement text.

doxysphinx.utils.files.multi_replace_in_file(file: pathlib.Path, *search_replace_pair: Tuple[str, str])

Replace text inside a file. Supports multiple replacements.

Parameters:

• file – The file to do the replacement in.

• search_replace_pair – an argument list of search and replacement text pairs.

doxysphinx.utils.files.multi_glob(directory: pathlib.Path, *patterns: str) → List[pathlib.Path]

Evaluate multiple glob patterns at once.

Parameters:

• directory – The source directory (where to evaluate the glob pattern)

• patterns – The glob patterns as list or multi-arguments

Returns:

The list of found files/directories

doxysphinx.utils.files.copy_if_different(source_dir: pathlib.Path, target_dir: pathlib.Path, *patterns: str, ignore_files: List[pathlib.Path] | None = None) → List[pathlib.Path]

Copy files with given glob patterns from source_dir to target_dir but only if the files are different.

Parameters:

• source_dir – The source directory of the files to copy

• target_dir – The target directory where the files are copied to

• patterns – glob patterns for the source files

Returns:

a list of all files that were copied (target files)

doxysphinx.utils.files.stringify_paths(paths: Iterable[pathlib.Path]) → str

Convert a list of paths to a bulleted string where each path is on a new line.

doxysphinx.utils.files.hash_blake2b(file: pathlib.Path, chunk_size: int = 65536) → str

Fast file hash based on blake2b hash algorithm.

Parameters:

• file – Path to a file to calculate the hash for

• chunk_size – The size of the chunks that are read from the file. Use this if you really need to optimize for performance for your special use case. Note that the default (64k) turned out the fastest in some very naive adhoc tests… so there may be room for improvement here.