xotl.tools.fs – file system utilities

File system utilities.

This module contains file-system utilities that could have side-effects. For path-handling functions that have no side-effects look at xotl.tools.fs.path.

xotl.tools.fs.ensure_filename(filename, yields=False)[source]

Ensures the existence of a file with a given filename.

If the filename is taken and is not pointing to a file (or a link to a file) an OSError is raised. If exist_ok is False the filename must not be taken; an OSError is raised otherwise.

The function creates all directories if needed. See makedirs() for restrictions.

If yields is True, returns the file object. This way you may open a file for writing like this:

with ensure_filename('/tmp/good-name-87.txt', yields=True) as fh:
    fh.write('Do it!')

The file is open in mode ‘w+b’.

New in version 1.6.1: Added parameter yield.

xotl.tools.fs.imap(func, pattern)[source]

Yields func(file_0, stat_0), func(file_1, stat_1), … for each dir path. The pattern may contain:

  • Simple shell-style wild-cards à la fnmatch.
  • Regex if pattern starts with ‘(?’. Expressions must be valid, as in “(?:[^.].*)$” or “(?i).*.jpe?g$”. Remember to add the end mark ‘$’ if needed.
xotl.tools.fs.iter_dirs(top='.', pattern=None, regex_pattern=None, shell_pattern=None)[source]

Iterate directories recursively.

The params have analagous meaning that in iter_files() and the same restrictions.

xotl.tools.fs.iter_files(top='.', pattern=None, regex_pattern=None, shell_pattern=None, followlinks=False, maxdepth=None)[source]

Iterate filenames recursively.

Parameters:
  • top – The top directory for recurse into.
  • pattern – A pattern of the files you want to get from the iterator. It should be a string. If it starts with “(?” it will be regarded as a regular expression, otherwise a shell pattern.
  • regex_pattern – An alternative to pattern. This will always be regarded as a regular expression.
  • shell_pattern – An alternative to pattern. This should be a shell pattern.
  • followlinks – The same meaning that in os.walk.
  • maxdepth – Only files above this level will be yielded. If None, no limit is placed.

Warning

It’s an error to pass more than pattern argument.

Changed in version 1.2.1: Added parameters followlinks and maxdepth.

xotl.tools.fs.listdir(path)[source]

Same as os.listdir but normalizes path and raises no error.

xotl.tools.fs.rmdirs(top='.', pattern=None, regex_pattern=None, shell_pattern=None, exclude=None, confirm=None)[source]

Removes all empty dirs at top.

Parameters:
  • top – The top directory to recurse into.
  • pattern – A pattern of the dirs you want to remove. It should be a string. If it starts with “(?” it will be regarded as a regular expression, otherwise a shell pattern.
  • exclude – A pattern of the dirs you DON’T want to remove. It should be a string. If it starts with “(?” it will be regarded as a regular expression, otherwise a shell pattern. This is a simple commodity to have you not to negate complex patterns.
  • regex_pattern – An alternative to pattern. This will always be regarded as a regular expression.
  • shell_pattern – An alternative to pattern. This should be a shell pattern.
  • confirm – A callable that accepts a single argument, which is the path of the directory to be deleted. confirm should return True to allow the directory to be deleted. If confirm is None, then all matched dirs are deleted.

Note

In order to avoid common mistakes we won’t attempt to remove mount points.

New in version 1.1.3.

xotl.tools.fs.stat(path)[source]

Return file or file system status.

This is the same as the function os.stat but raises no error.

xotl.tools.fs.walk_up(start, sentinel)[source]

Given a start directory walk-up the file system tree until either the FS root is reached or the sentinel is found.

The sentinel must be a string containing the file name to be found.

Warning

If sentinel is an absolute path that exists this will return start, no matter what start is (in windows this could be even different drives).

If start path exists but is not a directory an OSError is raised.

xotl.tools.fs.concatfiles(*files, target)[source]

Concat several files to a single one.

Each positional argument must be either:

The last positional argument is the target. If it’s file-like object it must be open for writing, and the caller is the responsible for closing it.

Alternatively if there are only two positional arguments and the first is a collection, the sources will be the members of the first argument.

xotl.tools.fs.makedirs(path, mode=0o777, exist_ok=False)[source]

Recursive directory creation function. Like os.mkdir(), but makes all intermediate-level directories needed to contain the leaf directory.

The default mode is 0o777 (octal). On some systems, mode is ignored. Where it is used, the current umask value is first masked out.

If exist_ok is False (the default), an OSError is raised if the target directory already exists.

Note

makedirs() will become confused if the path elements to create include os.pardir (eg. “..” on UNIX systems).

This function handles UNC paths correctly.

Changed in version 1.6.1: Behaves as Python 3.4.1.

Before Python 3.4.1 (ie. xotl.tools 1.6.1), if exist_ok was True and the directory existed, makedirs() would still raise an error if mode did not match the mode of the existing directory. Since this behavior was impossible to implement safely, it was removed in Python 3.4.1. See the original os.makedirs().

Contents: