Package that contains file manipulation functions. More...

Functions
	is_write_protected (path_name)
	Test if a file is write protected.
	make_executable (exe_path)
	Set the executable flag to true on a file.
	create_folder_if_needed (path)
	Given a pathname to a folder, if the folder doesn't exist, create it.
	delete_file (filename)
	Given a pathname to a file, delete it.
	is_source_newer (source, destination)
	Return False if the source file is older then the destination file.
	copy_file_if_needed (source, destination, verbose=True, perforce=False)
	Copy a file only if newer than the destination.
	copy_directory_if_needed (source, destination, exception_list=None, verbose=True)
	Copy all of the files in a directory into a new directory.
	shutil_readonly_cb (func, path, exception_info)
	Subroutine for shutil.rmtree() to delete read only files.
	readonly312_cb (func, path, exception_info)
	Subroutine for shutil.rmtree() to delete read only files.
	delete_directory (path, delete_read_only=False)
	Recursively delete a directory.
	clean_directories (path, name_list, recursive=False, delete_read_only=False)
	Recursively clean directories with a name list.
	clean_files (path, name_list, recursive=False, delete_read_only=False)
	Recursively clean files with a filename list.
	get_tool_path (tool_folder, tool_name, encapsulate=False)
	Find executable tool directory.
	traverse_directory (working_dir, filename_list, terminate=False, find_directory=False)
	Create a list of all copies of a file following a directory.
	unlock_files (working_dir, recursive=False)
	Iterate over a directory and unlock all read-only files.
	lock_files (lock_list)
	Iterate over the input list and mark all files as read-only.
	load_text_file (file_name)
	Load in a text file as a list of lines.
	save_text_file (file_name, text_lines, line_feed=None, bom=False)
	Save in a text file from an iterable of lines.
	compare_files (filename1, filename2)
	Compare text files for equality.
	compare_file_to_string (file_name, text_lines)
	Compare text file and a string for equality.
	read_zero_terminated_string (filep, encoding="utf-8")
	Read a zero terminated string from an open binary file.
	save_text_file_if_newer (file_name, text_lines, line_feed=None, bom=False, perforce=False, verbose=False)
	Save in a text file from an iterable of lines if newer.
	environment_root (test_directory, env_name, working_directory=None)
	Check if a directory is relative to an environment variable.

Detailed Description

Package that contains file manipulation functions.

Function Documentation

◆ clean_directories()

burger.fileutils.clean_directories	(	path,
		name_list,
		recursive = False,
		delete_read_only = False )

Recursively clean directories with a name list.

Parameters

path	Pathname of the directory to scan
name_list	Iterable of directory names
recursive	Boolean if recursive clean is desired
delete_read_only	True if read only files are to be deleted as well

Examples

# Delete all temp and __pycache__ files recursively
burger.fileutils.clean_directories(
    ".",
    ("*.temp", "__pycache__"),
    True)

See also: clean_files; delete_directory

◆ clean_files()

burger.fileutils.clean_files	(	path,
		name_list,
		recursive = False,
		delete_read_only = False )

Recursively clean files with a filename list.

Parameters

path	Pathname of the directory to scan
name_list	Iterable of file names
recursive	Boolean if recursive clean is desired
delete_read_only	True if read only files are to be deleted as well

Examples

# Delete all .obj and .lib files recursively

burger.fileutils.clean_files("temp", ("*.obj", "*.lib"), True)

burger.fileutils.clean_files

clean_files(path, name_list, recursive=False, delete_read_only=False)

Recursively clean files with a filename list.

Definition fileutils.py:473

See also: delete_file; delete_directory

◆ compare_file_to_string()

burger.fileutils.compare_file_to_string	(		file_name,
			text_lines )

Compare text file and a string for equality.

Check if a text file is the same as a string by loading the text file and testing line by line to verify the equality of the contents

Parameters

file_name	string object with the pathname of the file to test
text_lines	string object to test against

Returns: True if the file and the string are the same, False if not

See also: compare_files

◆ compare_files()

burger.fileutils.compare_files	(		filename1,
			filename2 )

Compare text files for equality.

Check if two text files are the same length, and then test the contents to verify equality.

Parameters

filename1	string object with the pathname of the file to test
filename2	string object with the pathname of the file to test against

Returns: True if the files are equal, False if not.

See also: compare_file_to_string

◆ copy_directory_if_needed()

burger.fileutils.copy_directory_if_needed	(	source,
		destination,
		exception_list = None,
		verbose = True )

Copy all of the files in a directory into a new directory.

Creating any necessary directories in the process, and it will skip files with specific extensions

Note: This is a recursive function

Parameters

source	string pathname of the directory to copy from
destination	string pathname of the directory to copy to
exception_list	optional list of file extensions to ignore during copy
verbose	True if print output is desired

Returns: Zero if no error, non-zero on error

See also: copy_file_if_needed; create_folder_if_needed

◆ copy_file_if_needed()

burger.fileutils.copy_file_if_needed	(	source,
		destination,
		verbose = True,
		perforce = False )

Copy a file only if newer than the destination.

Copy a file only if the destination is missing or is older than the source file.

Parameters

source	string pathname of the file to copy from
destination	string pathname of the file to copy to
verbose	True if print output is desired
perforce	True if Perforce "p4 edit" should be done on the destination.

Returns: Zero if no error otherwise IOError.errno

See also: is_source_newer

◆ create_folder_if_needed()

burger.fileutils.create_folder_if_needed ( path )

Given a pathname to a folder, if the folder doesn't exist, create it.

Call os.makedirs(path) but does not throw an exception if the directory already exists. All other exceptions are passed through with raise.

Parameters

path	A string object with the pathname.

See also: delete_directory

◆ delete_directory()

burger.fileutils.delete_directory	(		path,
			delete_read_only = False )

Recursively delete a directory.

Delete a directory and all of the files and directories within.

Parameters

path	Pathname of the directory to delete
delete_read_only	True if read only files are to be deleted as well

See also: shutil_readonly_cb; create_folder_if_needed

◆ delete_file()

burger.fileutils.delete_file ( filename )

Given a pathname to a file, delete it.

If the file doesn't exist, it will return without raising an exception.

Parameters

filename A string object with the filename

See also: delete_directory

◆ environment_root()

burger.fileutils.environment_root	(	test_directory,
		env_name,
		working_directory = None )

Check if a directory is relative to an environment variable.

Given a directory, check if it's in the directory of an environment variable and if so, return /foo/bar as a path. Otherwise, return the path relative to the working_directory or an absolute path if working_directory is not set or it's on another drive.

Parameters

test_directory	Path to test
env_name	Environment variable to check
working_directory	Optional root directory

Returns: Tuple with the first is the relative path, the second is a boolean if the environment variable is matched

◆ get_tool_path()

burger.fileutils.get_tool_path	(	tool_folder,
		tool_name,
		encapsulate = False )

Find executable tool directory.

For allowing builds on multiple operating system hosts under the Burgerlib way of project management, it's necessary to query what is the host operating system and glean out which folder to find a executable compiled for that specific host

Parameters

tool_folder	Pathname to the folder that contains the executables
tool_name	Bare name of the tool (Windows will append ".exe")
encapsulate	False if a path is requested, True if it's quoted to be used as a string to be sent to command line shell

Returns: Full pathname to the tool to execute

◆ is_source_newer()

burger.fileutils.is_source_newer	(		source,
			destination )

Return False if the source file is older then the destination file.

Check the modification times of both files to determine if the source file is newer. If the destination file is older or doesn't exist True is returned.

Return False if destination is newer, not False if not.

Examples

result = burger.fileutils.is_source_newer("file.c", "file.obj")

burger.fileutils.is_source_newer

is_source_newer(source, destination)

Return False if the source file is older then the destination file.

Definition fileutils.py:166

if result == 2: build_file_c()

if result: compile("file.c", "file.obj") else:

print("Already built")

Note: If the source file does not exist, the function will return 2. This is to allow proper error checking if the source is required to exist.

Parameters

source	string pathname of the file to test
destination	string pathname of the file to test against

Returns: False if not newer, True if newer, 2 if there is no source file

◆ is_write_protected()

burger.fileutils.is_write_protected ( path_name )

Test if a file is write protected.

If the file/directory exists, it is tested if it's write protected. If it exists and is write protected, True is returned, otherwise False is returned.

Parameters

path_name Path name to the file/directory

Returns: True if the file exists and is write protected

◆ load_text_file()

burger.fileutils.load_text_file ( file_name )

Load in a text file as a list of lines.

Read in a text file as a list of lines and handle all three line ending types (\r, \n and \r\n)

Note: This function assumes the file is utf-8 with or without a byte order mark.

Parameters

file_name File to load

Returns: A list object with the file

See also: save_text_file; compare_files

◆ lock_files()

burger.fileutils.lock_files ( lock_list )

Iterate over the input list and mark all files as read-only.

Parameters

lock_list Iterable object containing a list of path names to files or directories to mark as "read-only"

See also: unlock_files

◆ make_executable()

burger.fileutils.make_executable ( exe_path )

Set the executable flag to true on a file.

Parameters

exe_path Pathname to the executable to fix up.

◆ read_zero_terminated_string()

burger.fileutils.read_zero_terminated_string	(		filep,
			encoding = "utf-8" )

Read a zero terminated string from an open binary file.

Read in a stream of bytes and stop at the end of file or a terminating zero. The string will be converted from utf-8 into unicode by default before returning.

Parameters

filep	File record of a file opened in binary mode
encoding	Character set encoding of the string

Returns: None or the unicode string (Without the terminating zero)

◆ readonly312_cb()

burger.fileutils.readonly312_cb	(	func,
		path,
		exception_info )

Subroutine for shutil.rmtree() to delete read only files.

shutil.rmtree() raises an exception if there are read only files in the directory being deleted. Use this callback to allow read only files to be disposed of.

This is for Python 3.12 or later

Example

Note: This is a callback function

Parameters

func	Action function
path	pathname of the file that is read only
exception_info	Information about the exception

See also: delete_directory

◆ save_text_file()

burger.fileutils.save_text_file	(	file_name,
		text_lines,
		line_feed = None,
		bom = False )

Save in a text file from an iterable of lines.

Save a text file from an iterable of lines and allow custom line endings. If line_feed is None, the line feed will be the system default.

Note: This function will write out the text file using utf-8 encoding.

Parameters

file_name	File to load
text_lines	Lines to save
line_feed	String to use as a line feed
bom	If True write the UTF-8 Byte Order Mark

See also: load_text_file

◆ save_text_file_if_newer()

burger.fileutils.save_text_file_if_newer	(	file_name,
		text_lines,
		line_feed = None,
		bom = False,
		perforce = False,
		verbose = False )

Save in a text file from an iterable of lines if newer.

Compare an iterable of lines to a pre-existing text file. If the text file either exists or differs from the input, write a new text file to disk.

Note: This function will write out the text file using utf-8 encoding.

Parameters

file_name	File to load
text_lines	Lines to save
line_feed	String to use as a line feed
bom	If True write the UTF-8 Byte Order Mark
perforce	Enable perforce checkout or add if True
verbose	Enable messages if True

Returns: True if no change was performed, False if the file was written

See also: save_text_file; compare_file_to_string; perforce_edit; perforce_add

◆ shutil_readonly_cb()

burger.fileutils.shutil_readonly_cb	(	func,
		path,
		exception_info )

Subroutine for shutil.rmtree() to delete read only files.

shutil.rmtree() raises an exception if there are read only files in the directory being deleted. Use this callback to allow read only files to be disposed of.

Examples

import burger
import shutil
 
shutil.rmtree(PATH_TO_DIRECTORY,onerror = burger.shutil_readonly_cb)

Note: This is a callback function

Parameters

func	Not used
path	pathname of the file that is read only
exception_info	Information about the exception

See also: delete_directory

◆ traverse_directory()

burger.fileutils.traverse_directory	(	working_dir,
		filename_list,
		terminate = False,
		find_directory = False )

Create a list of all copies of a file following a directory.

Starting with a working directory, test if a file exists and if so, insert it into a list. The list will be starting from the root with the last entry being at the working directory

Parameters

working_dir	string with the path of the folder to start the search
filename_list	string or an iterable of strings with the name(s) of the file(s) to find in the scanned folders
terminate	True if searching will end on the first found file
find_directory	True if searching for directories instead of files.

Returns: List of pathnames (With filename appended)

◆ unlock_files()

burger.fileutils.unlock_files	(		working_dir,
			recursive = False )

Iterate over a directory and unlock all read-only files.

This function will generate a list of fully qualified pathnames of every file that was unlocked. Directories will be skipped.

Examples

# Any file that is read only in this directory is now unlocked
lock_list = unlock_files("~/projects/lockedfiles")
 
# Do stuff on the files
do_code_on_unlocked_files()
 
# Re-lock all the files that were unlocked.
lock_files(lock_list)

Parameters

working_dir	Pathname to the directory to traverse for read-only files
recursive	False (default) don't recurse through folders, True, recurse

Returns: A list object with the name of every file that was unlocked.

See also: lock_files

Functions

Detailed Description

Function Documentation

◆ clean_directories()

◆ clean_files()

◆ compare_file_to_string()

◆ compare_files()

◆ copy_directory_if_needed()

◆ copy_file_if_needed()

◆ create_folder_if_needed()

◆ delete_directory()

◆ delete_file()

◆ environment_root()

◆ get_tool_path()

◆ is_source_newer()

◆ is_write_protected()

◆ load_text_file()

◆ lock_files()

◆ make_executable()

◆ read_zero_terminated_string()

◆ readonly312_cb()

◆ save_text_file()

◆ save_text_file_if_newer()

◆ shutil_readonly_cb()

◆ traverse_directory()

◆ unlock_files()