fstools (Filesystem Tools)

Author:

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'))

25f66094936cc9dd79b14c2a16ebd27194ea619f

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