mosey.Walker ¶

def check_walk_can_start(
    self,
    root: os.PathLike[str] | str,
    *,
    start: os.PathLike[str] | str = ".",
) -> None:
    """Check that a walk can start, without walking.

    This runs exactly the checks that [`walk`][mosey.Walker.walk] runs before it
    returns its iterator, and raises exactly what `walk` raises for them: the same
    exceptions, naming the same paths, as listed under `walk`'s "Raises". It lists
    nothing within `start`, and reads no ignore-files, as documented at
    [starting directories][starting-directories].

    Args:
        root: Path to the directory to walk.
        start: Path to the subdirectory to start in, relative to `root`. The
            default, `"."`, starts in `root` itself.
    """
    ...

def walk(
    self,
    root: os.PathLike[str] | str,
    *,
    start: 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. The ignore-files themselves aren't yielded either,
    unless the name was set with `ignore=False`, or a pattern re-includes them.

    When the walker ignores symlinks (set by
    [`Mosey.ignore_symlinks`][mosey.Mosey.ignore_symlinks]), it yields none.

    With `start`, the walk yields only what a walk of `root` yields within that
    subdirectory, and lists nothing beside it, as documented at
    [starting directories][starting-directories].

    To run the checks listed under "Raises" without walking, call
    [`check_walk_can_start`][mosey.Walker.check_walk_can_start].

    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.
        start: Path to the subdirectory to start in, relative to `root`. The
            default, `"."`, starts in `root` itself.

    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.

            Without `start`, `root` itself isn't listed until the first step is
            requested. With it, `root` and every directory down to `start` are
            listed straight away, to check `start`.

    Raises:
        FileNotFoundError: When `root` or `start` is empty, doesn't exist, or can't
            exist (e.g. when its parent isn't a directory). `start` can't exist
            beneath a symlink either, and each of its names has to be spelled
            exactly as the file system lists it.
        NotADirectoryError: When `root` or `start` isn't a directory, or `start` is
            a symlink, even one to 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, or can't list a
            directory on the way to `start`.
        PermissionError: When file system permissions deny reaching or listing
            `root`, or listing `start` or a directory on the way to it.
        ValueError: When `root` or `start` contains a null character, or `start` is
            absolute, has a drive, or holds `".."`.
    """
    ...