fs.walk

The machinery for walking a filesystem. See Walking for details.

class fs.walk.BoundWalker(fs, walker_class=<class 'fs.walk.Walker'>)[source]

A class that binds a Walker instance to a FS object.

Parameters:
  • fs – A FS object.
  • walker_class – A WalkerBase sub-class. The default uses Walker.

You will typically not need to create instances of this class explicitly. Filesystems have a walk property which returns a BoundWalker object.

>>> import fs
>>> home_fs = fs.open_fs('~/')
>>> home_fs.walk
BoundWalker(OSFS('/Users/will', encoding='utf-8'))

A BoundWalker is callable. Calling it is an alias for walk().

dirs(path=u'/', **kwargs)[source]

Walk a filesystem, yielding absolute paths to directories.

Parameters:
  • path (str) – A path to a directory.
  • ignore_errors (bool) – If true, any errors reading a directory will be ignored, otherwise exceptions will be raised.
  • on_error (callable) – If ignore_errors is false, then this callable will be invoked with a path and the exception object. It should return True to ignore the error, or False to re-raise it.
  • search (str) – If 'breadth' then the directory will be walked top down. Set to 'depth' to walk bottom up.
  • exclude_dirs (list) – A list of patterns that will be used to filter out directories from the walk, e.g. ['*.svn', '*.git'].
Returns:

An iterable of directory paths (absolute from the FS root).

This method invokes dirs() with the bound FS object.

files(path=u'/', **kwargs)[source]

Walk a filesystem, yielding absolute paths to files.

Parameters:
  • path (str) – A path to a directory.
  • ignore_errors (bool) – If true, any errors reading a directory will be ignored, otherwise exceptions will be raised.
  • on_error (callable) – If ignore_errors is false, then this callable will be invoked with a path and the exception object. It should return True to ignore the error, or False to re-raise it.
  • search (str) – If 'breadth' then the directory will be walked top down. Set to 'depth' to walk bottom up.
  • filter (list) – If supplied, this parameter should be a list of file name patterns, e.g. ['*.py']. Files will only be returned if the final component matches one of the patterns.
  • exclude_dirs (list) – A list of patterns that will be used to filter out directories from the walk, e.g. ['*.svn', '*.git'].
Returns:

An iterable of file paths (absolute from the filesystem root).

This method invokes files() with the bound FS object.

info(path=u'/', namespaces=None, **kwargs)[source]

Walk a filesystem, yielding tuples of (<absolute path>, <resource info>).

Parameters:
  • path (str) – A path to a directory.
  • ignore_errors (bool) – If true, any errors reading a directory will be ignored, otherwise exceptions will be raised.
  • on_error (callable) – If ignore_errors is false, then this callable will be invoked with a path and the exception object. It should return True to ignore the error, or False to re-raise it.
  • search (str) – If 'breadth' then the directory will be walked top down. Set to 'depth' to walk bottom up.
  • filter (list) – If supplied, this parameter should be a list of file name patterns, e.g. ['*.py']. Files will only be returned if the final component matches one of the patterns.
  • exclude_dirs (list) – A list of patterns that will be used to filter out directories from the walk, e.g. ['*.svn', '*.git'].
Returns:

An iterable Info objects.

This method invokes info() with the bound FS object.

walk(path=u'/', namespaces=None, **kwargs)[source]

Walk the directory structure of a filesystem.

Parameters:
  • path (str) – A path to a directory.
  • ignore_errors (bool) – If true, any errors reading a directory will be ignored, otherwise exceptions will be raised.
  • on_error (callable) – If ignore_errors is false, then this callable will be invoked with a path and the exception object. It should return True to ignore the error, or False to re-raise it.
  • search (str) – If 'breadth' then the directory will be walked top down. Set to 'depth' to walk bottom up.
  • filter (list) – If supplied, this parameter should be a list of file name patterns, e.g. ['*.py']. Files will only be returned if the final component matches one of the patterns.
  • exclude_dirs (list) – A list of patterns that will be used to filter out directories from the walk, e.g. ['*.svn', '*.git'].
Returns:

Step iterator.

The return value is an iterator of (<path>, <dirs>, <files>) named tuples, where <path> is an absolute path to a directory, and <dirs> and <files> are a list of Info objects for directories and files in <path>.

Here’s an example:

home_fs = open_fs('~/')
walker = Walker(filter=['*.py'])
for path, dirs, files in walker.walk(home_fs, namespaces=['details']):
    print("[{}]".format(path))
    print("{} directories".format(len(dirs)))
    total = sum(info.size for info in files)
    print("{} bytes {}".format(total))

This method invokes walk() with bound FS object.

class fs.walk.Step(path, dirs, files)
dirs

Alias for field number 1

files

Alias for field number 2

path

Alias for field number 0

class fs.walk.Walker(ignore_errors=False, on_error=None, search=u'breadth', filter=None, exclude_dirs=None)[source]

A walker object recursively lists directories in a filesystem.

Parameters:
  • ignore_errors (bool) – If true, any errors reading a directory will be ignored, otherwise exceptions will be raised.
  • on_error (callable) – If ignore_errors is false, then this callable will be invoked with a path and the exception object. It should return True to ignore the error, or False to re-raise it.
  • search (str) – If 'breadth' then the directory will be walked top down. Set to 'depth' to walk bottom up.
  • filter (list) – If supplied, this parameter should be a list of filename patterns, e.g. ['*.py']. Files will only be returned if the final component matches one of the patterns.
  • exclude_dirs (list) – A list of patterns that will be used to filter out directories from the walk. e.g. ['*.svn', '*.git'].
classmethod bind(fs)[source]

This binds in instance of the Walker to a given filesystem, so that you won’t need to explicitly provide the filesystem as a parameter. Here’s an example of binding:

>>> from fs import open_fs
>>> from fs.walk import Walker
>>> home_fs = open_fs('~/')
>>> walker = Walker.bind(home_fs)
>>> for path in walker.files(filter=['*.py']):
...     print(path)

Unless you have written a customized walker class, you will be unlikely to need to call this explicitly, as filesystem objects already have a walk attribute which is a bound walker object. Here’s how you might use it:

>>> from fs import open_fs
>>> home_fs = open_fs('~/')
>>> for path in home_fs.walk.files(filter=['*.py']):
...     print(path)
Parameters:fs – A filesystem object.
Returns:a BoundWalker
check_file(fs, info)[source]

Check if a filename should be included in the walk. Override to exclude files from the walk.

Parameters:
  • fs (FS) – A FS object.
  • info – A Info object.
Return type:

bool

check_open_dir(fs, info)[source]

Check if a directory should be opened. Override to exclude directories from the walk.

Parameters:
  • fs (FS) – A FS object.
  • info – A Info object.
Return type:

bool

filter_files(fs, infos)[source]

Filters a sequence of resource Info objects.

The default implementation filters those files for which check_file() returns True.

Parameters:
  • fs (FS) – A FS object.
  • infos (list) – A list of Info instances.
Return type:

list

walk(fs, path=u'/', namespaces=None)[source]

Walk the directory structure of a filesystem.

Parameters:
  • fs – A FS object.
  • path (str) – a path to a directory.
  • namespaces (list) – A list of additional namespaces to add to the Info objects.
Returns:

Step iterator.

The return value is an iterator of (<path>, <dirs>, <files>) named tuples, where <path> is an absolute path to a directory, and <dirs> and <files> are a list of Info objects for directories and files in <path>.

Here’s an example:

home_fs = open_fs('~/')
walker = Walker(filter=['*.py'])
for path, dirs, files in walker.walk(home_fs, namespaces=['details']):
    print("[{}]".format(path))
    print("{} directories".format(len(dirs)))
    total = sum(info.size for info in files)
    print("{} bytes {}".format(total))
class fs.walk.WalkerBase[source]

The base class for a Walker.

To create a custom walker, implement walk() in a sub-class.

See Walker() for a fully featured walker object that should be adequate for all but your most exotic directory walking needs.

dirs(fs, path=u'/')[source]

Walk a filesystem, yielding absolute paths to directories.

Parameters:
  • fs (str) – A FS object.
  • path (str) – A path to a directory.
files(fs, path=u'/')[source]

Walk a filesystem, yielding absolute paths to files.

Parameters:
  • fs – A FS object.
  • path (str) – A path to a directory.
Returns:

An iterable of file paths.

info(fs, path=u'/', namespaces=None)[source]

Walk a filesystem, yielding tuples of (<absolute path>, <resource info>).

Parameters:
  • fs (str) – A FS object.
  • path (str) – A path to a directory.
  • namespaces (list) – A list of additional namespaces to add to the Info objects.
Returns:

An iterable of Info objects.

walk(fs, path=u'/', namespaces=None)[source]

Walk the directory structure of a filesystem.

Parameters:
  • fs – A FS object.
  • path (str) – a path to a directory.
  • namespaces (list) – A list of additional namespaces to add to the Info objects.
Returns:

Iterator of Step named tuples.