Skip to main content

fs_utils

Utility functions to interact with the filesystem.

Module​

Functions​

get_file_creation_date​

def get_file_creation_date(    path: Union[str, os.PathLike], stat: Optional[os.stat_result] = None,) ‑> datetime.date:

Get the creation date of a file with consideration for different OSs.

If the stat object is provided, then the information will be extracted from this in preference to getting a new one from the filesystem. Note that there is no checking that the stat object is up-to-date or even corresponds to the same file as path, so care should be taken to pass through the correct object.

caution

It is not possible to get the creation date of a file on Linux. This method will return the last modification date instead. This will impact filtering of files by date.

Arguments

  • path: The path to the file.
  • stat: An optional stat_result object for the file, as returned by os.stat(path). This can be used to avoid making a new filesystem query.

Returns The creation date of the file.

get_file_last_modification_date​

def get_file_last_modification_date(    path: Union[str, os.PathLike], stat: Optional[os.stat_result] = None,) ‑> datetime.date:

Get the last modification date of a file.

If the stat object is provided, then the information will be extracted from this in preference to getting a new one from the filesystem. Note that there is no checking that the stat object is up-to-date or even corresponds to the same file as path, so care should be taken to pass through the correct object.

Arguments

  • path: The path to the file.
  • stat: An optional stat_result object for the file, as returned by os.stat(path). This can be used to avoid making a new filesystem query.

Returns The last modification date of the file.

get_file_size​

def get_file_size(    path: Union[str, os.PathLike], stat: Optional[os.stat_result] = None,) ‑> int:

Get the size, in bytes, of a file on the filesystem.

If the stat object is provided, then the information will be extracted from this in preference to getting a new one from the filesystem. Note that there is no checking that the stat object is up-to-date or even corresponds to the same file as path, so care should be taken to pass through the correct object.

Arguments

  • path: The path to the file.
  • stat: An optional stat_result object for the file, as returned by os.stat(path). This can be used to avoid making a new filesystem query.

Returns The size of the file, in bytes.

is_file​

def is_file(    path: Union[str, os.PathLike, os.DirEntry], stat: Optional[os.stat_result] = None,) ‑> bool:

Determine if a path is a file or not.

If the stat object is provided, then the information will be extracted from this in preference to getting a new one from the filesystem. Note that there is no checking that the stat object is up-to-date or even corresponds to the same file as path, so care should be taken to pass through the correct object.

Arguments

  • path: The path to check. Can also be an os.DirEntry as from scandir() or scantree().
  • stat: An optional stat_result object for the path, as returned by os.stat(path). This can be used to avoid making a new filesystem query.

Returns The size of the file, in bytes.

safe_write_to_file​

def safe_write_to_file(func: Callable[[Path], R], initial_path: Path) ‑> tuple:

Handle PermissionError when writing to a file.

Execute some function that writes to a file and if it's not possible to write due to a PermissionError (e.g. the user has opened the file in Windows so can't be appended to) try to write to a new file instead.

Arguments

  • func: Function to execute, that takes in the destination file path.
  • initial_path: The desired destination file path.

Returns A tuple of the result of the function and the actual path finally written to.

scantree​

def scantree(root: Union[str, os.PathLike]) ‑> collections.abc.Iterator:

Recursively iterate through a folder as in scandir(), yielding file entries.