fs.walk¶
Machinery for walking a filesystem.
Walking a filesystem means recursively visiting a directory and any sub-directories. It is a fairly common requirement for copying, searching etc. See Walking for details.
-
class
fs.walk.
BoundWalker
(fs, walker_class=<class 'fs.walk.Walker'>)¶ A class that binds a
Walker
instance to aFS
instance.Parameters: - fs (FS) – A filesystem instance.
- walker_class (type, optional) – A
WalkerBase
sub-class. The default usesWalker
.
You will typically not need to create instances of this class explicitly. Filesystems have a
walk
property which returns aBoundWalker
object.Example
>>> 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 forwalk
.-
dirs
(path=u'/', **kwargs)¶ Walk a filesystem, yielding absolute paths to directories.
Parameters: path (str) – A path to a directory.
Keyword Arguments: - ignore_errors (bool) – If
True
, any errors reading a directory will be ignored, otherwise exceptions will be raised. - on_error (callable) – If
ignore_errors
isFalse
, then this callable will be invoked with a path and the exception object. It should returnTrue
to ignore the error, orFalse
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 filesystem root).
Return type: iterable
This method invokes
Walker.dirs
with the boundFS
object.- ignore_errors (bool) – If
-
files
(path=u'/', **kwargs)¶ Walk a filesystem, yielding absolute paths to files.
Parameters: path (str) – A path to a directory.
Keyword Arguments: - ignore_errors (bool) – If
True
, any errors reading a directory will be ignored, otherwise exceptions will be raised. - on_error (callable) – If
ignore_errors
isFalse
, then this callable will be invoked with a path and the exception object. It should returnTrue
to ignore the error, orFalse
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).
Return type: Iterable
This method invokes
Walker.files
with the boundFS
object.- ignore_errors (bool) – If
-
info
(path=u'/', namespaces=None, **kwargs)¶ Walk a filesystem, yielding path and
Info
of resources.Parameters: Keyword Arguments: - ignore_errors (bool) – If
True
, any errors reading a directory will be ignored, otherwise exceptions will be raised. - on_error (callable) – If
ignore_errors
isFalse
, then this callable will be invoked with a path and the exception object. It should returnTrue
to ignore the error, orFalse
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 yielding tuples of
(<absolute path>, <resource info>)
.Return type: Iterable
This method invokes
Walker.info
with the boundFS
object.- ignore_errors (bool) – If
-
walk
(path=u'/', namespaces=None, **kwargs)¶ Walk the directory structure of a filesystem.
Parameters: Keyword Arguments: - ignore_errors (bool) – If
True
, any errors reading a directory will be ignored, otherwise exceptions will be raised. - on_error (callable) – If
ignore_errors
isFalse
, then this callable will be invoked with a path and the exception object. It should returnTrue
to ignore the error, orFalse
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 iterator of
(<path>, <dirs>, <files>)
named tuples, where<path>
is an absolute path to a directory, and<dirs>
and<files>
are a list ofInfo
objects for directories and files in<path>
.Return type: Iterator
Example
>>> home_fs = open_fs('~/') >>> walker = Walker(filter=['*.py']) >>> for path, dirs, files in walker.walk(home_fs, ['details']): ... print("[{}]".format(path)) ... print("{} directories".format(len(dirs))) ... total = sum(info.size for info in files) ... print("{} bytes {}".format(total))
This method invokes
Walker.walk
with boundFS
object.- ignore_errors (bool) – If
-
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)¶ A walker object recursively lists directories in a filesystem.
Parameters: - ignore_errors (bool, optional) – If
True
, any errors reading a directory will be ignored, otherwise exceptions will be raised. - on_error (callable, optional) – If
ignore_errors
isFalse
, then this callable will be invoked for a path and the exception object. It should returnTrue
to ignore the error, orFalse
to re-raise it. - search (str, optional) – If
'breadth'
then the directory will be walked top down. Set to'depth'
to walk bottom up. - filter (list, optional) – 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, optional) – A list of patterns that will be used
to filter out directories from the walk. e.g.
['*.svn', '*.git']
.
-
classmethod
bind
(fs)¶ Bind a
Walker
instance to a given filesystem.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.
Parameters: fs (FS) – A filesystem object. Returns: a bound walker. Return type: BoundWalker Example
>>> 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.Example
>>> from fs import open_fs >>> home_fs = open_fs('~/') >>> for path in home_fs.walk.files(filter=['*.py']): ... print(path)
-
check_file
(fs, info)¶ Check if a filename should be included.
Override to exclude files from the walk.
Parameters: Returns: True
if the file should be included.Return type:
-
check_open_dir
(fs, info)¶ Check if a directory should be opened.
Override to exclude directories from the walk.
Parameters: Returns: True
if the directory should be opened.Return type:
-
filter_files
(fs, infos)¶ Filter a sequence of resource
Info
objects.The default implementation filters those files for which
check_file
returnsTrue
.Parameters: Returns: a list of
Info
objects passing thecheck_file
validation.Return type:
-
walk
(fs, path=u'/', namespaces=None)¶ Walk the directory structure of a filesystem.
Parameters: Returns: an iterator of
Step
instances.Return type: collections.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 ofInfo
objects for directories and files in<path>
.Example
>>> home_fs = open_fs('~/') >>> walker = Walker(filter=['*.py']) >>> namespaces = ['details'] >>> for path, dirs, files in walker.walk(home_fs, namespaces) ... print("[{}]".format(path)) ... print("{} directories".format(len(dirs))) ... total = sum(info.size for info in files) ... print("{} bytes {}".format(total))
- ignore_errors (bool, optional) – If
-
class
fs.walk.
WalkerBase
¶ 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'/')¶ Walk a filesystem, yielding absolute paths to directories.
Parameters: Yields: str – absolute path to directories on the filesystem found recursively within the given directory.
-
files
(fs, path=u'/')¶ Walk a filesystem, yielding absolute paths to files.
Parameters: Yields: str – absolute path to files on the filesystem found recursively within the given directory.
-
info
(fs, path=u'/', namespaces=None)¶ Walk a filesystem, yielding tuples of
(<path>, <info>)
.Parameters: Yields: (str, Info) – a tuple of
(<absolute path>, <resource info>)
.
-