xpybuild.utils.fileutils

Functions for manipulating files and paths including xpybuild.utils.fileutils.openForWrite, xpybuild.utils.fileutils.mkdir, xpybuild.utils.fileutils.toLongPathSafe and xpybuild.utils.fileutils.parsePropertiesFile.

openForWrite

xpybuild.utils.fileutils.openForWrite = <built-in function open>

Open a file for writing and return a corresponding text or binary stream file object.

This has the same semantics as open/io.open, but should be used instead of open/io.open to avoid file system race conditions on Windows. This class must be used from a with clause.

mkdir

xpybuild.utils.fileutils.mkdir(newdir)

Recursively create the specified directory if it doesn’t already exist.

If it does, exit without error.

Parameters

newdir – The path to create.

Returns

newdir, to allow fluent use of this method.

deleteDir

xpybuild.utils.fileutils.deleteDir(path, allowRetry=True)

Recursively delete the contents of a directory.

Contains magic hacks so it works even on paths that exceed the Windows MAX_PATH 260 character length.

Parameters

• path – the path to delete.

• allowRetry – set to False to disable automatic retry of the deletion after a few seconds (in case the error was transient)

deleteFile

xpybuild.utils.fileutils.deleteFile(path, allowRetry=True)

Delete the specified file, with the option of automatically retrying a few times if the first attempt fails (to get around Windows weirdness), throwing an exception if the file still exists at the end of retrying.

Use this instead of os.remove for improved robustness.

Does nothing if the file doesn’t already exist.

Contains magic hacks so it works even on paths that exceed the Windows MAX_PATH 260 character length.

Parameters

• path – The path to delete.

• allowRetry – If true, wait for a bit and retry the removal if it fails (default: true)

parsePropertiesFile

xpybuild.utils.fileutils.parsePropertiesFile(lines, excludeLines=None)

Parse the contents of the specified properties file or line list, and return an ordered list of (key,value,lineno) pairs.

If desired, convert this to a dict using:

{k:v for (k,v,lineno) in parsePropertiesFile(...)}

Parameters

• lines – an open file handle or a sequence that can be iterated over to get each line in the file.

• excludeLines – a string of list of strings to search for, any KEY containing these strings will be ignored

>>> parsePropertiesFile(['a','b=c',' z  =  x', 'a=d #foo', '#g=h'])
[('b', 'c', 2), ('z', 'x', 3), ('a', 'd', 4)]
>>> parsePropertiesFile(['a=b','c=d#foo','XfooX=e', 'f=h'], excludeLines='foo')
[('a', 'b', 1), ('c', 'd', 2), ('f', 'h', 4)]
>>> parsePropertiesFile(['a=b','c=d#foo','XfooX=e', 'f=h'], excludeLines=['foo','h'])
[('a', 'b', 1), ('c', 'd', 2), ('f', 'h', 4)]

isDirPath

xpybuild.utils.fileutils.isDirPath(path)

Returns true if the path is a directory (ends with / or ).

>>> isDirPath(None)
False

>>> isDirPath('/')
True

>>> isDirPath('a/')
True

>>> isDirPath('a'+os.sep)
True

toLongPathSafe

xpybuild.utils.fileutils.toLongPathSafe(path, force=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 string starting with \\?\ must be used to get correct behaviour for long paths.

Unlike normLongPath which also performs the long path conversion, this function does NOT convert to a canonical form, normalize slashes or remove ‘..’ elements (unless required for long path support). It is therefore faster.

Parameters

• path – A path. Must not be a relative path. Can be None/empty. Can contain “..” sequences, though performance is a lot lower if it does.

• force – Normally the long path support is added only if this path exceeds the maximum length on this OS (e.g. 256 chars) or ends with a directory slash. Set force to True to add long path support regardless of length, which allows extra characters to be added on to the end of the string (e.g. “.log” or a directory filename) safely.

Returns

The passed-in path, possibly with a \\?\ prefix added and forward slashes converted to backslashes on Windows. Any trailing slash is preserved by this function (though will be converted to a backslash).

normPath

xpybuild.utils.fileutils.normPath(path)

Normalizes but does NOT absolutize a path (os.path.normpath). This converts an absolute or relative path to a canonical form (e.g. normalizing the case of the drive letter on Windows), but unlike normLongPath does not add the \\?\ prefix needed to permit long paths or absolutize.

Parameters

path – the absolute path to be converted should be a unicode string where possible, as specifying a byte string will not work if the path contains non-ascii characters.

normLongPath

xpybuild.utils.fileutils.normLongPath(path)

Normalizes and absolutizes a path (os.path.abspath), converts to a canonical form (e.g. normalizing the case of the drive letter on Windows), and on windows adds the \\?\ prefix needed to force correct handling of long (>256 chars) paths (same as toLongPathSafe).

Parameters

path – the absolute path to be converted should be a unicode string where possible, as specifying a byte string will not work if the path contains non-ascii characters.

cached_stat

xpybuild.utils.fileutils.cached_stat(path, errorIfMissing=False)

Cached-once os.stat (DO NOT USE if you expect it to change after startup). Returns False if missing.

cached_getmtime

xpybuild.utils.fileutils.cached_getmtime(path)

Cached-once os.getmtime (DO NOT USE if you expect it to change after startup)

cached_getsize

xpybuild.utils.fileutils.cached_getsize(path)

Cached-once os.path.getsize (DO NOT USE if you expect it to change after startup)

cached_exists

xpybuild.utils.fileutils.cached_exists(path)

Cached-once os.path.exists (DO NOT USE if you expect it to change after startup)

cached_isfile

xpybuild.utils.fileutils.cached_isfile(path)

Cached-once os.path.isfile (DO NOT USE if you expect it to change after startup)

cached_isdir

xpybuild.utils.fileutils.cached_isdir(path)

Cached-once os.path.isdir (DO NOT USE if you expect it to change after startup)