Package: cs.fs
Assorted filesystem related utility functions,
some of which have been bloating cs.fileutils for too long.Latest release 20240201:FSPathBasedSingleton: drop the default_factory parameter/attribute, let default_attr specify a callable.Singleton._resolve_fspath: fix reference to class name.Functionatomic_directory(*da, **dkw)Decorator for a function which fills in a directory
which calls the function against a temporary directory
then renames the temporary to the target name on completion.Parameters:infill_func: the function to fill in the target directorymake_placeholder: optional flag, defaultFalse:
if true an empty directory will be make at the target name
and after completion it will be removed and the completed
directory renamed to the target nameFunctionfnmatchdir(dirpath, fnglob)Return a list of the names indirpathmatching the globfnglob.ClassFSPathBasedSingleton(cs.obj.SingletonMixin, HasFSPath)The basis for aSingletonMixinbased onrealpath(self.fspath).MethodFSPathBasedSingleton.__init__(self, fspath: Optional[str] = None, lock=None):
Initialise the singleton:On the first call:set.fspathtoself._resolve_fspath(fspath)set._locktolock(orthreading.Lock()if not specified)returnTrueOn subsequent calls returnFalse.ClassHasFSPathAn object with a.fspathattribute representing a filesystem location.Functionis_valid_rpath(rpath, log=None) -> boolTest thatrpathis a clean relative path with no funny business.This is a Boolean wrapper forvalidate_rpath().Functionlongpath(path, prefixes=None)Returnpathwith prefixes and environment variables substituted.
The converse ofshortpath().Functionneeddir(dirpath, mode=511, *, use_makedirs=False, log=None)Create the directorydirpathif missing.Parameters:dirpath: the required directory pathmode: the permissions mode, default0o777log: logmakedirsormkdircalluse_makedirs: optional creation mode, defaultFalse;
if true, useos.makedirs, otherwiseos.mkdirFunctionrpaths(dirpath='.', *, only_suffixes=None, skip_suffixes=None, sort_paths=False)Yield relative file paths from a directory.Parameters:dirpath: optional top directory, default'.'only_suffixes: optional iterable of suffixes of interest;
if provided only files ending in these suffixes will be yieldedskip_suffixes: optional iterable if suffixes to ignore;
if provided files ending in these suffixes will not be yieldedsort_paths: optional flag specifying that filenames should be sorted,
defaultFalseFunctionshortpath(path, prefixes=None)Returnpathwith the first matching leading prefix replaced.Parameters:environ: environment mapping if not os.environprefixes: optional iterable of(prefix,subst)to consider for replacement;
eachprefixis subject to environment variable
substitution before consideration
The default considers "$HOME/" for replacement by "~/".Functionvalidate_rpath(rpath: str)Test thatrpathis a clean relative path with no funny business;
raiseValueErrorif the test fails.Tests:not empty or '.' or '..'not an absolute pathnormaliseddoes not walk up out of its parent directoryExamples:>>> validate_rpath('')
False
>>> validate_rpath('.')Release LogRelease 20240201:FSPathBasedSingleton: drop the default_factory parameter/attribute, let default_attr specify a callable.Singleton._resolve_fspath: fix reference to class name.Release 20231129:HasFSPath: new listdir method.HasFSPath.pathto: accept multiple relative subpaths.FSPathBasedSingleton: accept cls.FSPATH_FACTORY as a factory function for the default fspath, makes it possible to defer the path lookup.Replace is_clean_subpath with validate_rpath/is_valid_rpath pair.Release 20230806:Reimplement fnmatchdir using fnmatch.filter.No longer claim Python 2 compatibility.Release 20230401:
HasFSPath.shortpath: hand call before .fspath set.Release 20221221:
Replace use of cs.env.envsub with os.path.expandvars and drop unused environ parameter.Release 20220918:FSPathBasedSingleton.init: return True on the first call, False on subsequent calls.FSPathBasedSingleton.init: probedictfor '_lock' instead of using hasattr (which plays poorly this early on with classes with their owngetattr).needdir: accept optionallogparameter to log mkdir or makedirs.HasFSPath: add a defaultstr.Release 20220805:
Doc update.Release 20220530:
FSPathBasedSingleton._resolve_fspath: newenvvaranddefault_attrparameters.Release 20220429:New HasFSPath and FSPathBasedSingleton.Add longpath and shortpath from cs.fileutils.New is_clean_subpath(subpath).New needdir(path).New fnmatchdir(dirpath,fnglob) pulled out from HasFSPath.fnmatch(fnglob).Release 20220327:
New module cs.fs to contain more filesystem focussed functions than cs.fileutils, which is feeling a bit bloated.