--- a/src/eric7/SystemUtilities/FileSystemUtilities.py Wed Dec 06 16:33:04 2023 +0100
+++ b/src/eric7/SystemUtilities/FileSystemUtilities.py Thu Dec 07 10:32:10 2023 +0100
@@ -46,8 +46,10 @@
Function returning a path, that is normalized with respect to its case
and references.
- @param path file path (string)
- @return case normalized path (string)
+ @param path file path
+ @type str
+ @return case normalized path
+ @rtype str
"""
return os.path.normcase(os.path.normpath(path))
@@ -57,8 +59,10 @@
Function returning an absolute path, that is normalized with respect to
its case and references.
- @param path file path (string)
- @return absolute, normalized path (string)
+ @param path file path
+ @type str
+ @return absolute, normalized path
+ @rtype str
"""
return os.path.normcase(os.path.abspath(path))
@@ -67,9 +71,12 @@
"""
Function returning a normalized path of the joined parts passed into it.
- @param a first path to be joined (string)
- @param p variable number of path parts to be joined (string)
- @return normalized path (string)
+ @param a first path to be joined
+ @type str
+ @param p variable number of path parts to be joined
+ @type str
+ @return normalized path
+ @rtype str
"""
return os.path.normpath(os.path.join(a, *p))
@@ -79,9 +86,12 @@
Function returning a normalized, absolute path of the joined parts passed
into it.
- @param a first path to be joined (string)
- @param p variable number of path parts to be joind (string)
- @return absolute, normalized path (string)
+ @param a first path to be joined
+ @type str
+ @param p variable number of path parts to be joined
+ @type str
+ @return absolute, normalized path
+ @rtype str
"""
return os.path.abspath(os.path.join(a, *p))
@@ -90,9 +100,11 @@
"""
Function to check for an executable file.
- @param file filename of the executable to check (string)
- @return flag to indicate, if the executable file is accessible
- via the searchpath defined by the PATH environment variable.
+ @param file filename of the executable to check
+ @type str
+ @return flag indicating, if the executable file is accessible via the executable
+ search path defined by the PATH environment variable.
+ @rtype bool
"""
if os.path.isabs(file):
return os.access(file, os.X_OK)
@@ -132,10 +144,13 @@
Function to convert a file path to a path relative to a start path
with universal separators.
- @param path file or directory name to convert (string)
- @param start start path (string)
+ @param path file or directory name to convert
+ @type str
+ @param start start path
+ @type str
@return relative path or unchanged path, if path does not start with
- the start path with universal separators (string)
+ the start path with universal separators
+ @rtype str
"""
return fromNativeSeparators(os.path.relpath(path, start))
@@ -145,9 +160,12 @@
Public method to convert a path relative to a start path to an
absolute path.
- @param path file or directory name to convert (string)
- @param start start path (string)
- @return absolute path (string)
+ @param path file or directory name to convert
+ @type str
+ @param start start path
+ @type str
+ @return absolute path
+ @rtype str
"""
if not os.path.isabs(path):
path = os.path.normpath(os.path.join(start, path))
@@ -159,9 +177,12 @@
Public method to convert a path relative to a start path with
universal separators to an absolute path.
- @param path file or directory name to convert (string)
- @param start start path (string)
- @return absolute path with native separators (string)
+ @param path file or directory name to convert
+ @type str
+ @param start start path
+ @type str
+ @return absolute path with native separators
+ @rtype str
"""
if not os.path.isabs(path):
path = toNativeSeparators(os.path.normpath(os.path.join(start, path)))
@@ -172,10 +193,12 @@
"""
Function to build the full path of an executable file from the environment.
- @param file filename of the executable to check (string)
+ @param file filename of the executable to check
+ @type str
@return full executable name, if the executable file is accessible
- via the searchpath defined by the PATH environment variable, or an
+ via the executable search path defined by the PATH environment variable, or an
empty string otherwise.
+ @rtype str
"""
if os.path.isabs(file):
if os.access(file, os.X_OK):
@@ -206,10 +229,12 @@
"""
Function to build all full path of an executable file from the environment.
- @param file filename of the executable (string)
- @return list of full executable names (list of strings), if the executable
- file is accessible via the searchpath defined by the PATH environment
- variable, or an empty list otherwise.
+ @param file filename of the executable
+ @type str
+ @return list of full executable names, if the executable file is accessible via
+ the executable search path defined by the PATH environment variable, or an
+ empty list otherwise.
+ @rtype list of str
"""
paths = []
@@ -245,10 +270,12 @@
such with the extensions .cmd or .bat and finally the given file name as
is. The first match is returned.
- @param file filename of the executable to check (string)
- @return full executable name, if the executable file is accessible
- via the searchpath defined by the PATH environment variable, or an
+ @param file filename of the executable to check
+ @type str
+ @return full executable name, if the executable file is accessible via the
+ executable search path defined by the PATH environment variable, or an
empty string otherwise.
+ @rtype str
"""
if os.path.isabs(file):
if os.access(file, os.X_OK):
@@ -283,8 +310,10 @@
"""
Function to check, if a file is executable.
- @param exe filename of the executable to check (string)
- @return flag indicating executable status (boolean)
+ @param exe filename of the executable to check
+ @type str
+ @return flag indicating executable status
+ @rtype bool
"""
return os.access(exe, os.X_OK)
@@ -311,40 +340,62 @@
return isWindowsDrive
-def samepath(f1, f2):
+def samepath(f1, f2, followSymlinks=True):
"""
Function to compare two paths.
- @param f1 first path for the compare (string)
- @param f2 second path for the compare (string)
+ @param f1 first filepath for the compare
+ @type str
+ @param f2 second filepath for the compare
+ @type str
+ @param followSymlinks flag indicating to respect symbolic links for the comparison
+ (i.e. compare the real paths) (defaults to True)
+ @type bool (optional)
@return flag indicating whether the two paths represent the
- same path on disk.
+ same path on disk
+ @rtype bool
"""
if f1 is None or f2 is None:
return False
- if normcaseabspath(os.path.realpath(f1)) == normcaseabspath(os.path.realpath(f2)):
- return True
+ if followSymlinks:
+ if normcaseabspath(os.path.realpath(f1)) == normcaseabspath(
+ os.path.realpath(f2)
+ ):
+ return True
+ else:
+ if normcaseabspath(f1) == normcaseabspath(f2):
+ return True
return False
-def samefilepath(f1, f2):
+def samefilepath(f1, f2, followSymlinks=True):
"""
Function to compare two paths. Strips the filename.
- @param f1 first filepath for the compare (string)
- @param f2 second filepath for the compare (string)
+ @param f1 first filepath for the compare
+ @type str
+ @param f2 second filepath for the compare
+ @type str
+ @param followSymlinks flag indicating to respect symbolic links for the comparison
+ (i.e. compare the real paths) (defaults to True)
+ @type bool (optional)
@return flag indicating whether the two paths represent the
- same path on disk.
+ same path on disk
+ @rtype bool
"""
if f1 is None or f2 is None:
return False
- if normcaseabspath(os.path.dirname(os.path.realpath(f1))) == normcaseabspath(
- os.path.dirname(os.path.realpath(f2))
- ):
- return True
+ if followSymlinks:
+ if normcaseabspath(os.path.dirname(os.path.realpath(f1))) == normcaseabspath(
+ os.path.dirname(os.path.realpath(f2))
+ ):
+ return True
+ else:
+ if normcaseabspath(os.path.dirname(f1)) == normcaseabspath(os.path.dirname(f2)):
+ return True
return False
@@ -359,8 +410,10 @@
"""
Function to split a pathname into a directory part and a file part.
- @param name path name (string)
- @return a tuple of 2 strings (dirname, filename).
+ @param name path name
+ @type str
+ @return tuple containing directory name and file name
+ @rtype tuple of (str, str)
"""
if os.path.isdir(name):
dn = os.path.abspath(name)
@@ -377,9 +430,12 @@
The leading "." of ext is replaced by a platform specific extension
separator if necessary.
- @param prefix the basepart of the filename (string)
- @param ext the extension part (string)
- @return the complete filename (string)
+ @param prefix the basepart of the filename
+ @type str
+ @param ext the extension part
+ @type str
+ @return the complete filename
+ @rtype str
"""
if ext[0] != ".":
ext = ".{0}".format(ext)
@@ -391,11 +447,15 @@
"""
Function to return a compacted path fitting inside the given width.
- @param path path to be compacted (string)
- @param width width for the compacted path (integer)
+ @param path path to be compacted
+ @type str
+ @param width width for the compacted path
+ @type int
@param measure reference to a function used to measure the length of the
string
- @return compacted path (string)
+ @type function(str)
+ @return compacted path
+ @rtype str
"""
if measure(path) <= width:
return path
@@ -451,7 +511,7 @@
@type list of str
@return list of all files and directories in the tree rooted
at path. The names are expanded to start with path.
- @rtype list of strs
+ @rtype list of str
"""
patterns = pattern if isinstance(pattern, list) else [pattern]
files = [] if filesonly else [path]
@@ -508,8 +568,11 @@
Function returning a list of all directories below path.
@param path root of the tree to check
- @param excludeDirs basename of directories to ignore
+ @type str
+ @param excludeDirs base name of directories to ignore
+ @type list of str
@return list of all directories found
+ @rtype list of str
"""
try:
dirs = []
