IO Utilities

General IO Functions

class tgtools.utils.ioutils.iogen.FileType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

String enumeration for ‘file’ and ‘dir’.

tgtools.utils.ioutils.iogen.confirm_exists(path_file: Path, filetype: FileType | str = FileType.file, create: bool = False) → bool

Check if path_file exists. If it does, and it is of type filetype, return True. If file exists, but is of the wrong filetype, return False.

If the file doesn’t exist, then:

  • If create is True, then create the file and return True;

  • Otherwise, return False.

Parameters:

  • path_file (pathlib.Path) – Path to file.

  • filetype (FileType) – Type of file.

  • create (bool) – Indicates whether to create a file that doesn’t already exist.

Return type:

bool

tgtools.utils.ioutils.iogen.enforce_max_files(path_dir: Path, max_number_files: int, glob_pattern: str) → int

If the number of files matching glob_pattern in path_dir exceed max_number_files, then delete the oldest surplus files. It is assumed that the last characters of the files stem is a timestamp.

Parameters:

  • path_dir (pathlib.Path) – directory path

  • max_number_files (int) – maximum number of files permitted in directory

  • glob_pattern (str) – Glob pattern for files

Returns:

The number of files deleted

Return type:

int

tgtools.utils.ioutils.iogen.file_write(content: str, path_file: Path, threading_lock: lock | None = None) → bool

Write content to text file (overwrite file if it exists). This function can be made is thread-safe by providing a threading lock.

Parameters:

  • content (str) – Text to write to output text file.

  • path_file (pathlib.Path) – Path to output filename.

  • threading_lock (threading.Lock) – Optional threading lock for thread-safe operation.

Returns:

Indication if writing is successful.

Return type:

bool

CSV IO Functions

tgtools.utils.ioutils.iocsv.read_csv(file_path: Path) → list[dict]

Read csv file into list of dicts.

Parameters:

file_path (pathlib.Path) – Path to input csv file.

Return type:

list[dict]

tgtools.utils.ioutils.iocsv.write_csv(records: dict | Sequence[dict], path_file: Path, append: bool = True, fieldnames: Sequence[str] | None = None, threading_lock: lock | None = None)

Append a dict (or sequence of dicts) to csv file. It is assumed all dict keys are identical. If the output csv file does not exist, it is created, and the dict keys (fieldnames) written as the first line. Each subsequent line corresponds to the values of each dict. This method can be made thread-safe by providing a threading lock.

Parameters:

  • records (dict | collections.abc.Sequence[dict]) – A dict (or sequence of dicts).

  • path_file (pathlib.Path) – Path to output csv file.

  • append (bool) – Indicates whether to append to file if it exists (default), or overwrite file.

  • fieldnames (collection.abc.Sequence[str]) – Optional: csv fieldnames (if None, automatically derived from first record in records)

  • threading_lock (threading.Lock) – Optional threading lock for thread-safe operation