fstools (Filesystem Tools)¶
Author:
Dirk Alders <sudo-dirk@mount-mockery.de>
Description:
This module supports functions and classes to handle files and paths
Submodules:
Unittest:
See also the
unittest
documentation.
Module Documentation:
- fstools.dirlist(path='.', expression='*', rekursive=True)¶
Function returning a list of directories below a given path.
- Parameters:
path (str) – folder which is the basepath for searching files.
expression (str) – expression to fit including shell-style wildcards. It is only used for the first directory level, if rekursive is set to True.
rekursive (bool) – search all subfolders if True.
- Returns:
list of filenames including the pathe
- Return type:
list
Note
The returned filenames could be relative pathes depending on argument path.
Example:
#!/usr/bin/env python # -*- coding: UTF-8 -*- import sys sys.path.append('../..') import fstools for dirname in fstools.dirlist(path='..', rekursive=True): print(dirname)
../__pycache__ ../_docs_ ../_docs_/_sources ../_docs_/_downloads ../_docs_/_downloads/7bf10188aa659556c284b4a8298dba8d ../_docs_/_static ../_docs_/_static/css ../_docs_/_static/css/fonts ../_docs_/_static/fonts ../_docs_/_static/fonts/RobotoSlab ../_docs_/_static/fonts/Lato ../_docs_/_static/js ../_examples_ ../_testresults_
- fstools.filelist(path='.', expression='*', rekursive=True)¶
Function returning a list of files below a given path.
- Parameters:
path (str) – folder which is the basepath for searching files.
expression (str) – expression to fit including shell-style wildcards.
rekursive (bool) – search all subfolders if True.
- Returns:
list of filenames including the pathe
- Return type:
list
Note
The returned filenames could be relative pathes depending on argument path.
Example:
#!/usr/bin/env python # -*- coding: UTF-8 -*- import sys sys.path.append('../..') import fstools for filename in fstools.filelist(path='..', expression='*.py', rekursive=True): print(filename)
../__init__.py ../_examples_/dirlist.py ../_examples_/uid_filelist.py ../_examples_/uid.py ../_examples_/is_writeable.py ../_examples_/filelist.py
- fstools.is_writeable(path)¶
Method to get the Information, if a file or folder is writable.
- Parameters:
path (str) – file or folder to check.
- Returns:
Whether path is writable or not.
- Return type:
bool
Note
If path does not exist, the return Value is
False
.Example:
#!/usr/bin/env python # -*- coding: UTF-8 -*- import sys sys.path.append('../..') import fstools print(fstools.is_writeable('..')) print(fstools.is_writeable('../__init__.py'))
True True
- fstools.mkdir(path)¶
Method to create a folder.
Note
All needed subfoilders will also be created (rekursive mkdir).
- Parameters:
path (str) – folder to be created.
- Returns:
True, if folder exists after creation commands, otherwise False.
- Return type:
bool
- fstools.open_locked_blocking(*args, **kwargs)¶
Method to get exclusive access to a file.
- Parameters:
args – Arguments for a standard file open call.
kwargs – Keyword arguments for a standard file open call.
- Returns:
A file descriptor.
- Return type:
file handle
Note
The call blocks until file is able to be used. This can cause a deadlock, if the file release es done after trying to open the file!
- fstools.open_locked_non_blocking(*args, **kwargs)¶
Method to get exclusive access to a file.
- Parameters:
args – Arguments for a standard file open call.
kwargs – Keyword arguments for a standard file open call.
- Raises:
OSError, if the file is already blocked.
- Returns:
A file descriptor.
- Return type:
file handle
Note
The call blocks until file is able to be used. This can cause a deadlock, if the file release es done after trying to open the file!
- fstools.uid(path, max_staleness=3600)¶
Function returning a “unique” id for a given file or path.
- Parameters:
path (str) – File or folder to generate a uid for.
max_staleness (int) – If a file or folder is older than that, we may consider it stale and return a different uid - this is a dirty trick to work around changes never being detected. Default is 3600 seconds, use None to disable this trickery. See below for more details.
- Returns:
An object that changes value if the file changed, None is returned if there were problems accessing the file or folder.
- Return type:
str
Warning
Depending on the operating system capabilities and the way the file update is done, this function might return the same value even if the file has changed. It should be better than just using file’s mtime though. max_staleness tries to avoid the worst for these cases.
Note
If this function is used for a path, it will stat all pathes and files rekursively.
Example:
#!/usr/bin/env python # -*- coding: UTF-8 -*- import sys sys.path.append('../..') import fstools print(fstools.uid('../__init__.py'))
d121957b7605f7540b23d2552c2474ece58aa89c
Using just the file’s mtime to determine if the file has changed is not reliable - if file updates happen faster than the file system’s mtime granularity, then the modification is not detectable because the mtime is still the same.
This function tries to improve by using not only the mtime, but also other metadata values like file size and inode to improve reliability.
For the calculation of this value, we of course only want to use data that we can get rather fast, thus we use file metadata, not file data (file content).
- fstools.uid_filelist(path='.', expression='*', rekursive=True)¶
Function returning a unique id for a given file or path.
- Parameters:
path (str) – folder which is the basepath for searching files.
expression (str) – expression to fit including shell-style wildcards.
rekursive (bool) – search all subfolders if True.
- Returns:
An object that changes value if one of the files change.
- Return type:
str
Note
This UID is created out of the file content. Therefore it is more reliable then
fstools.uid()
, but also much slower.Example:
#!/usr/bin/env python # -*- coding: UTF-8 -*- import sys sys.path.append('../..') import fstools print(fstools.uid_filelist('..', '*.py', rekursive=True))
92a26594015be798c2a5b438595067e9