pysys.utils.fileutils

File and directory handling utility functions such as mkdir and deletedir, with enhanced error handling and support for long paths on Windows. Also some simple utilities for loading properties and JSON files.

toLongPathSafe

pysys.utils.fileutils.toLongPathSafe(path, onlyIfNeeded=False)

Converts the specified path string to a form suitable for passing to API calls if it exceeds the maximum path length on this OS.

Currently, this is necessary only on Windows, where a unicode string starting with \?must be used to get correct behaviour for long paths. On Windows this function also normalizes the capitalization of drive letters so they are always upper case regardless of OS version and current working directory.

Parameters

• path (str) – An absolute (not relative) path. Can be None/empty. Can contain “..” sequences. Note that no normalization of “..” sequences and slashes is performed if the path starts with \\?\ already or is non-Windows so if in doubt run the path through os.path.normpath before calling this method on it (\\?\ paths with incorrect slashes and .. sequences are not permitted by Windows).

• onlyIfNeeded (bool) – Set to True to only adds the long path support if this path exceeds the maximum length on this OS (e.g. 256 chars). You must keep this at False if you will be adding extra characters on to the end of the returned string.

Returns

The passed-in path, possibly with a \\?\ prefix added, forward slashes converted to backslashes on Windows, and drive letter capitalized. Trailing slashes may be removed.

fromLongPathSafe

pysys.utils.fileutils.fromLongPathSafe(path)

Strip off \\?\ prefixes added by toLongPathSafe.

pathexists

pysys.utils.fileutils.pathexists(path)

Returns True if the specified path is an existing file or directory, as returned by os.path.exists.

This method is safe to call on paths that may be over the Windows 256 character limit.

Parameters

path – If None or empty, returns True.

mkdir

pysys.utils.fileutils.mkdir(path)

Create a directory, with recursive creation of any parent directories.

This function is a no-op (does not throw) if the directory already exists.

Returns

Returns the path passed in.

deletedir

pysys.utils.fileutils.deletedir(path, retries=1, ignore_errors=False, onerror=None)

Recursively delete the specified directory, with optional retries.

Does nothing if it does not exist. Raises an exception if the deletion fails (unless onerror= is specified), but deletes as many files as possible before doing so.

This method will attempt to change the permissions/file attributes to permit deletion if necessary.

Parameters

• retries – The number of retries to attempt. This can be useful to work around temporary failures causes by Windows file locking.

• ignore_errors – If True, an exception is raised if the path exists but cannot be deleted.

• onerror – A callable with arguments (function, path, excinfo), called when an error occurs while deleting. See the documentation of onexc / onerror for shutil.rmtree for more information. On Python 3.12+ excinfo holds the exception object, in earlier versions it holds the tuple returned from sys.exc_info().

deletefile

pysys.utils.fileutils.deletefile(path, retries=1, ignore_errors=False)

Delete the specified file, with optional retries.

Does nothing if it does not exist.

Parameters

• path (str) – The path to be deleted. Will be converted to be long-path safe on Windows.

• retries (int) – The number of retries to attempt. This can be useful to work around temporary failures causes by Windows file locking.

• ignore_errors (bool) – If True, an exception is raised if the path exists but cannot be deleted.

listDirContents

pysys.utils.fileutils.listDirContents(path, recurse=True)

Recursively scans the specified directory and returns a sorted list of the file/directory paths under it suitable for diffing.

The contents are returned in a normalized form suitable for diffing: relative to the scanned path, with forward slashes on all platforms, a trailing slash for directories, and sorted to ensure deterministic results. Symbolic links are not searched.

For example this can be used with pysys.basetest.BaseTest.assertDiff like this:

self.assertDiff(
  self.write_text('MyDir-contents.txt', '\\n'.join(
    pysys.utils.fileutils.listDirContents(self.output+'/MyDir')
)))

Parameters

• path (str) – The absolute path to search.

• recurse (bool) – Set this to False to just include the specified directory but not any children.

Returns

A list of strings with the relative paths found, e.g. ["mysubdir/myfile.txt", "mysubdir/mysubsubdir/"].

New in version 2.0.

loadProperties

pysys.utils.fileutils.loadProperties(path, encoding='utf-8-sig')

Reads keys and values from the specified .properties file.

Support # and ! comments but does not perform any special handling of backslash \\ characters (either for escaping or for line continuation). Leading and trailing whitespace around keys and values is stripped. If you need handling of \\ escapes and/or expansion of ${...} placeholders this should be performed manually on the returned values.

Parameters

• path (str) – The absolute path to the properties file.

• encoding (str) – The encoding to use. The default is UTF-8 (with optional Byte Order Mark).

Return dict[str:str]

An ordered dictionary containing the keys and values from the file.

loadJSON

pysys.utils.fileutils.loadJSON(path, **kwargs)

Reads JSON from the specified path.

This is a small wrapper around Python’s json.load() function.

Parameters

• path (str) – The absolute path to the JSON file, which must be encoded using UTF-8 (with optional Byte Order Mark).

• kwargs – Keyword arguments will be passed to json.load().

Return obj

A dict, list, or other Python object representing the contents of the JSON file.