Skip to content

mosey.Walker

Bases: Protocol

A directory walker, built by Mosey.build.

Walker is the type to annotate walkers with: you never create one yourself.

A walker never changes once it's built, so one walker can take any number of walks, one after another or at the same time, on any number of threads. Each call to walk returns its own iterator: share the walker between threads, but never an iterator.

walk 

walk(root: PathLike[str] | str) -> Iterator[Step]

Walk a directory and yield a Step for every file not ignored.

Files are yielded in a deterministic walk order, documented at https://cariad.github.io/mosey/walk-order/.

The files and directories that the walker's patterns ignore aren't yielded or walked, nor are the files and directories within them.

Its patterns are the ones added by Mosey.add_pattern, and, when it has an ignore-file name (set by Mosey.set_ignore_filename), those in each directory's ignore-file, which is read when the walk reaches the directory.

A relative root is found from the working directory each time a subdirectory is read, so don't change the working directory during a walk.

Parameters:

Name Type Description Default
root PathLike[str] | str

Path to the directory to walk.

 required

Returns:

Type Description
Iterator[Step]

An iterator of Step; one for every file not ignored.

The iterator raises OSError when it can't list root or a directory beneath it, say because it vanished, or permissions deny reading it or searching the directory that holds it.

When the walker has an ignore-file name, it also raises OSError when it can't read an ignore-file, say because it's a broken symlink or permissions deny reading it.

root itself isn't listed until the first step is requested.

Raises:

Type Description
FileNotFoundError

When root is empty, doesn't exist, or can't exist (e.g. when its parent isn't a directory).
NotADirectoryError

When root isn't a directory.
OSError

When the operating system can't resolve root for another reason, like its name being too long or a loop of symlinks.
PermissionError

When file system permissions deny reaching or listing root.
ValueError

When root contains a null character.
Source code in src/mosey/walker.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def walk(self, root: os.PathLike[str] | str) -> Iterator[Step]:
    """Walk a directory and yield a [`Step`][mosey.Step] for every file not ignored.

    Files are yielded in a deterministic walk order, documented at
    https://cariad.github.io/mosey/walk-order/.

    The files and directories that the walker's patterns ignore aren't yielded or
    walked, nor are the files and directories within them.

    Its patterns are the ones added by
    [`Mosey.add_pattern`][mosey.Mosey.add_pattern], and, when it has an ignore-file
    name (set by [`Mosey.set_ignore_filename`][mosey.Mosey.set_ignore_filename]),
    those in each directory's [ignore-file][ignore-files], which is read when the
    walk reaches the directory.

    A relative root is found from the working directory each time a subdirectory is
    read, so don't change the working directory during a walk.

    Args:
        root: Path to the directory to walk.

    Returns:
        An iterator of [`Step`][mosey.Step]; one for every file not ignored.

            The iterator raises [`OSError`][] when it can't list `root` or a
            directory beneath it, say because it vanished, or permissions deny
            reading it or searching the directory that holds it.

            When the walker has an ignore-file name, it also raises [`OSError`][]
            when it can't read an ignore-file, say because it's a broken symlink or
            permissions deny reading it.

            `root` itself isn't listed until the first step is requested.

    Raises:
        FileNotFoundError: When `root` is empty, doesn't exist, or can't exist (e.g.
            when its parent isn't a directory).
        NotADirectoryError: When `root` isn't a directory.
        OSError: When the operating system can't resolve `root` for another reason,
            like its name being too long or a loop of symlinks.
        PermissionError: When file system permissions deny reaching or listing
            `root`.
        ValueError: When `root` contains a null character.
    """
    ...