Burgerlib Python
Loading...
Searching...
No Matches
Functions
burger.fileutils Namespace Reference

Package that contains file manipulation functions. More...

Functions

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

Detailed Description

Package that contains file manipulation functions.

Function Documentation

◆ clean_directories()

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

Recursively clean directories with a name list.

Parameters
pathPathname of the directory to scan
name_listIterable of directory names
recursiveBoolean if recursive clean is desired

Examples

# Delete all temp and __pycache__ files recursively
".",
("*.temp", "__pycache__"),
True)
def clean_directories(path, name_list, recursive=False)
Recursively clean directories with a name list.
Definition: fileutils.py:385
See also
clean_files
delete_directory

◆ clean_files()

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

Recursively clean files with a filename list.

Parameters
pathPathname of the directory to scan
name_listIterable of file names
recursiveBoolean if recursive clean is desired

Examples

# Delete all .obj and .lib files recursively
burger.fileutils.clean_files("temp", ("*.obj", "*.lib"), True)
def clean_files(path, name_list, recursive=False)
Recursively clean files with a filename list.
Definition: fileutils.py:422
See also
delete_file
delete_directory

◆ compare_file_to_string()

def 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_namestring object with the pathname of the file to test
text_linesstring object to test against
Returns
True if the file and the string are the same, False if not
See also
compare_files

◆ compare_files()

def 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
filename1string object with the pathname of the file to test
filename2string 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()

def 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
sourcestring pathname of the directory to copy from
destinationstring pathname of the directory to copy to
exception_listoptional list of file extensions to ignore during copy
verboseTrue 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()

def 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
sourcestring pathname of the file to copy from
destinationstring pathname of the file to copy to
verboseTrue if print output is desired
perforceTrue 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()

def 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
pathA string object with the pathname.
See also
delete_directory

◆ delete_directory()

def 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
pathPathname of the directory to delete
delete_read_onlyTrue if read only files are to be deleted as well
See also
shutil_readonly_cb
create_folder_if_needed

◆ delete_file()

def 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
filenameA string object with the filename
See also
delete_directory

◆ get_tool_path()

def 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_folderPathname to the folder that contains the executables
tool_nameBare name of the tool (Windows will append ".exe")
encapsulateFalse 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()

def 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")
def is_source_newer(source, destination)
Return False if the source file is older then the destination file.
Definition: fileutils.py:165

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
sourcestring pathname of the file to test
destinationstring 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()

def 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_namePath name to the file/directory
Returns
True if the file exists and is write protected

◆ load_text_file()

def 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_nameFile to load
Returns
A list object with the file
See also
save_text_file
compare_files

◆ lock_files()

def burger.fileutils.lock_files (   lock_list)

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

Parameters
lock_listIterable object containing a list of path names to files or directories to mark as "read-only"
See also
unlock_files

◆ make_executable()

def burger.fileutils.make_executable (   exe_path)

Set the executable flag to true on a file.

Parameters
exe_pathPathname to the executable to fix up.

◆ read_zero_terminated_string()

def 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
filepFile record of a file opened in binary mode
encodingCharacter set encoding of the string
Returns
None or the unicode string (Without the terminating zero)

◆ save_text_file()

def 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_nameFile to load
text_linesLines to save
line_feedString to use as a line feed
bomIf True write the UTF-8 Byte Order Mark
See also
load_text_file

◆ save_text_file_if_newer()

def 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_nameFile to load
text_linesLines to save
line_feedString to use as a line feed
bomIf True write the UTF-8 Byte Order Mark
perforceEnable perforce checkout or add if True
verboseEnable 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()

def 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
funcNot used
pathpathname of the file that is read only
exception_infoInformation about the exception
See also
delete_directory

◆ traverse_directory()

def 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_dirstring with the path of the folder to start the search
filename_liststring or an iterable of strings with the name(s) of the file(s) to find in the scanned folders
terminateTrue if searching will end on the first found file
find_directoryTrue if searching for directories instead of files.
Returns
List of pathnames (With filename appended)

◆ unlock_files()

def 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_dirPathname to the directory to traverse for read-only files
recursiveFalse (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