Files

File Utilities

This module provides functions for working with files and folders, including file search, text replacement, and file and folder deletion.

phasefieldx.files.append_results_to_file(output_file_path, header, step, *data)

Appends results to a specified file, including a header if the file is empty.

Parameters:

output_file_pathstr

The path to the file where results will be appended.

headerstr

The header line to write if the file is empty.

stepint or str

The step number or identifier to write at the beginning of the line.

*datatuple

Variable length argument list containing the data to append, which will be tab-separated.

Notes

• If the file specified by output_file_path is empty, the header will be written first.

• Each subsequent call will append a new line with the step and data values.

Examples

>>> append_results_to_file('results.txt', 'Time     Value1  Value2', 1, 0.5, 1.2)
>>> append_results_to_file('results.txt', 'Time     Value1  Value2', 2, 0.6, 1.3)

phasefieldx.files.delete_folder(folder_path)

Recursively deletes a folder and its contents.

Parameters:

folder_pathstr

The path to the folder to be deleted.

Raises:

OSError

If an error occurs during the deletion process.

Notes

This function iterates over all items in the specified folder, removing files and recursively calling itself for subdirectories. Finally, it removes the empty folder.

Examples

>>> delete_folder('/path/to/your/folder')
Folder '/path/to/your/folder' and its contents deleted successfully.

phasefieldx.files.delete_folders_with_contents(folder_path, folder_names)

Delete specified folders and their contents from a given folder.

This function iterates through the specified folder names and deletes the corresponding folders along with their contents from the given folder.

Parameters:

folder_pathstr

Path to the folder containing the folders to be deleted.

folder_nameslist of str

List of folder names to be deleted.

Returns:

None

The function does not return any value.

Raises:

Exception

If an error occurs while deleting the folders.

phasefieldx.files.delete_specific_files(folder_path, extensions)

Delete files with specific extensions from a given folder.

This function iterates through all the files in the given folder and deletes files with extensions specified in the ‘extensions’ list.

Parameters:

folder_pathstr

Path to the folder containing the files.

extensionslist of str

List of file extensions to be deleted.

Returns:

None

The function does not return any value.

Raises:

Exception

If an error occurs while deleting the files.

phasefieldx.files.find_files_with_extension(folder_path: str, extension: str) → List[str]

Find files with the specified extension in the given folder.

Parameters:

folder_pathstr

The path of the folder.

extensionstr

The file extension to search for.

Returns:

List[str]

A list of file paths with the matching extension.

Examples

>>> folder_path = 'path/to/your/folder'
>>> extension = '.txt'
>>> files_with_extension = find_files_with_extension(folder_path, extension)
>>> for file_path in files_with_extension:
...     print(file_path)

phasefieldx.files.get_filenames_in_folder(folder_path: str) → List[str]

Get the filenames in the specified folder.

Parameters:

folder_pathstr

The path of the folder.

Returns:

List[str]

A list of filenames in the folder.

Examples

>>> folder_path = 'path/to/your/folder'
>>> filenames = get_filenames_in_folder(folder_path)
>>> for filename in filenames:
...     print(filename)

phasefieldx.files.get_foldernames_in_folder(folder_path: str) → List[str]

Get the folders in the specified folder.

Parameters:

folder_pathstr

The path of the folder.

Returns:

List[str]

A list of folders in the folder.

Examples

>>> folder_path = 'path/to/your/folder'
>>> folders = get_foldernames_in_folder(folder_path)
>>> for folder_name in folders:
...     print(folder_name)

phasefieldx.files.prepare_simulation(path, results_folder_name='results')

Prepare simulation directory by deleting specific files and folders.

This function prepares a simulation directory by deleting specific files and folders that are commonly generated during simulations and creates a folder with the specified name.

Parameters:

pathstr

Path to the simulation directory.

results_folder_namestr, optional

Name of the folder to be created. Default is “results”.

Returns:

None

The function does not return any value.

phasefieldx.files.read_last_line(file_path)

Read the last line of a specified file.

Parameters:

file_pathstr

The path to the file to be read.

Returns:

str or None

The last line of the file as a string, stripped of leading and trailing whitespace. Returns None if the file is empty.

Examples

>>> file_path = 'path/to/your/file.txt'
>>> last_line = read_last_line(file_path)
>>> if last_line is not None:
...     print("Last line:", last_line)
... else:
...     print("The file is empty.")

phasefieldx.files.read_last_lines(file_path, num_lines)

Read the specified number of lines from the end of a file.

Parameters:

file_pathstr

The path to the file to be read.

num_linesint

The number of lines to read from the end of the file.

Returns:

list

A list of strings representing the last num_lines lines of the file. If the file has fewer lines than num_lines, it will return all available lines.

Examples

>>> file_path = 'path/to/your/file.txt'
>>> num_lines = 5
>>> last_lines = read_last_lines(file_path, num_lines)
>>> for line in last_lines:
...     print(line)

phasefieldx.files.replace_text(original, target, list_replace)

Replaces specified patterns with corresponding strings in a file.

Parameters:

originalstr

Path to the original file.

targetstr

Path to the target file where the modified content will be saved.

list_replacelist

List of tuples, where each tuple contains the pattern to be replaced and its corresponding string.

Returns:

bool

True if the text is replaced successfully, False otherwise.

Examples

>>> original_file = "path/to/original/file.txt"
>>> target_file = "path/to/target/file.txt"
>>> replacements = [
...     ("pattern1", "replacement1"),
...     ("pattern2", "replacement2"),
...     ("pattern3", "replacement3")
... ]
>>> success = replace_text(original_file, target_file, replacements)
>>> if success:
...     print("Text replacement successful.")
... else:
...     print("Text replacement failed.")