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.

normalize_path​

def normalize_path(path: str | os.PathLike) ‑> pathlib.Path:

Normalize a path to handle mapped drives and UNC paths equivalently.

This function resolves mapped drives (e.g., S:\patients) to their UNC equivalents (e.g., \FSC\Filestorage1\Images\patients) so that paths referring to the same location are treated as equivalent.

On Windows, Path.resolve() automatically resolves mapped drives to UNC paths. On other platforms, this function resolves symlinks and relative paths.

Arguments

  • path: The path to normalize.

Returns A normalized and absolute Path object that can be used for path comparisons and operations like relative_to().

safe_append_to_file​

def safe_append_to_file(    func: Callable[[Path], R], initial_path: Path,) ‑> tuple[~R, pathlib.Path]:

Handle PermissionError when appending to a file.

Execute some function that writes/appends to a file and if it's not possible to append due to a PermissionError (e.g. the user has opened the file in Windows so can't be appended to) try backup paths to either create or append to.

The supplied func should take a single Path argument and return the result, but should be able to handle the case when the file doesn't exist (i.e. writing fresh) and when a file does exist but needs to be appended to.

Arguments

  • func: Function to execute, that takes in the destination file path and will append to an existing file or write to a new file.
  • initial_path: The desired destination file path.

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

safe_write_to_file​

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

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[posix.DirEntry]:

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

Classes​

MaxNetworkDriveRetriesExceededError​

class MaxNetworkDriveRetriesExceededError(*args, **kwargs):

Exception raised when the max number of network drive retries exceeded.

Ancestors​