# Welcome to fstools’s documentation!

## fstools (Filesystem Tools)

Author:

- Dirk Alders <sudo-dirk@mount-mockery.de>

Description:

> This module supports functions and classes to handle files and paths

Submodules:

- `fstools.dirlist()`
- `fstools.filelist()`
- `fstools.is_writeable()`
- `fstools.mkdir()`
- `fstools.open_locked_blocking()`
- `fstools.open_locked_non_blocking()`
- `fstools.uid()`

Unittest:

> See also the `unittest` documentation.

Module Documentation:

`fstools.``dirlist`(path='.', rekursive=True)

  Function returning a list of directories below a given path.

  Parameters:

  - path (str) – folder which is the basepath for searching files.
  - 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)

      ../_examples_
      ../__pycache__
      ../_testresults_
      ../_docs_
      ../_docs_/_static
      ../_docs_/_static/fonts
      ../_docs_/_static/fonts/Lato
      ../_docs_/_static/fonts/RobotoSlab
      ../_docs_/_static/js
      ../_docs_/_static/css
      ../_docs_/_static/css/fonts
      ../_docs_/_sources
      ../_docs_/_downloads
      ../_docs_/_downloads/7bf10188aa659556c284b4a8298dba8d

`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_/uid.py
      ../_examples_/is_writeable.py
      ../_examples_/uid_filelist.py
      ../_examples_/dirlist.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'))

      950bd674ce9e6ccc93a3f450964b524412961e0d

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

      32ca1c130dfa068b79f4e96071c46448

# Indices and tables

- Index
- Module Index
- Search Page