iterpath 0.4.0

安装

iterpath 需要 Python 3.7 或更高版本。只需使用 Python 3 的 pip 安装即可（您有 pip 吗？）

python3 -m pip install iterpath

示例

遍历此库的源代码仓库，跳过.git和test/data文件夹

>>> import os.path
>>> from iterpath import iterpath
>>> def filterer(dir_entry):
...     if dir_entry.name == ".git":
...         return False
...     elif dir_entry.path == os.path.join(".", "test", "data"):
...         return False
...     else:
...         return True
...
>>> with iterpath(".", sort=True, filter_dirs=filterer) as ip:
...     for p in ip:
...         print(p)
...
.github
.github/workflows
.github/workflows/test.yml
.gitignore
LICENSE
MANIFEST.in
README.rst
TODO.md
pyproject.toml
setup.cfg
src
src/iterpath
src/iterpath/__init__.py
src/iterpath/__pycache__
src/iterpath/__pycache__/__init__.cpython-39.pyc
src/iterpath/py.typed
test
test/test_iterpath.py
tox.ini

API

iterpath模块提供了一个名为iterpath的单一函数

iterpath(dirpath: AnyStr | os.PathLike[AnyStr] = os.curdir, **kwargs) -> Iterpath[AnyStr]

以深度优先顺序遍历以dirpath（默认为当前目录）为根的文件树，将文件和目录作为pathlib.Path实例生成。

返回值既是迭代器也是上下文管理器。为了确保内部os.scandir()迭代器被正确关闭，完成时可以调用close()方法，或者像这样将其用作上下文管理器

with iterpath(...) as ip:
    for path in ip:
        ...

如果return_relative为真，生成的Path对象将相对于dirpath。如果return_relative为假（默认值）且dirpath是绝对路径，则生成的Path对象将是绝对的；否则，如果dirpath是相对路径，则Path对象将是相对的，并且将以dirpath作为前缀。

请注意，尽管iterpath()生成pathlib.Path对象，但它内部在os.DirEntry对象上操作，因此任何作为sort_key参数或作为过滤器/排除参数提供的函数都必须接受os.DirEntry实例。

关键字参数

dirs: bool = True

是否在输出中包含目录

topdown: bool = True

是否在目录内容之前（True）或之后（False）生成每个目录

include_root: bool = False

是否将传递给iterpath()的dirpath参数包含在输出中

followlinks: bool = False

是否将目录的符号链接视为目录

return_relative: bool = False

如果为真，生成的路径将相对于dirpath

onerror: Optional[Callable[[OSError], Any]] = None

指定在迭代目录时遇到OSError时要调用的函数。如果函数重新引发异常，则iterpath()中止；否则，它将继续下一个目录。默认情况下，忽略OSError异常。

sort: bool = False

对每个目录中的条目进行排序。当False时，条目按os.scandir()返回的顺序生成。当True时，默认情况下，条目按文件名升序排序，但可以通过sort_key和sort_reverse参数进行更改。

sort_key: Optional[Callable[[os.DirEntry[AnyStr]], _typeshed.SupportsLessThan]] = None

指定用于排序目录条目的自定义键函数。只有当sort为True时才有作用。

sort_reverse: bool = False

以反向顺序排序目录条目。只有当sort为True时才有作用。

filter: Optional[Callable[[os.DirEntry[AnyStr]], Any]] = None

指定要应用于遇到的每个文件和目录的谓词；只有返回真值的那些文件和目录会被生成（对于目录，会进入其中）。

如果指定了filter，则指定filter_dirs或filter_files将是一个错误。

filter_dirs: Optional[Callable[[os.DirEntry[AnyStr]], Any]] = None

指定一个应用于所有遇到的目录的谓词；只有那些谓词返回真值的目录将被产生并进入

filter_files: 可选[Callable[[os.DirEntry[AnyStr]], Any]] = None

指定一个应用于所有遇到的文件的谓词；只有那些谓词返回真值的文件将被产生

exclude: 可选[Callable[[os.DirEntry[AnyStr]], Any]] = None

指定一个应用于所有遇到的文件和目录的谓词；只有那些谓词返回假值的文件和目录将被产生（对于目录，还将进入）

如果指定了 exclude，同时指定 exclude_dirs 或 exclude_files 将是一个错误。

exclude_dirs: 可选[Callable[[os.DirEntry[AnyStr]], Any]] = None

指定一个应用于所有遇到的目录的谓词；只有那些谓词返回假值的目录将被产生并进入

exclude_files: 可选[Callable[[os.DirEntry[AnyStr]], Any]] = None

指定一个应用于所有遇到的文件的谓词；只有那些谓词返回假值的文件将被产生

如果同时设置了 filter 和 exclude，则给定条目只有在 filter 返回真值且 exclude 返回假值时才会被包含（即，排除优先于包含），同样适用于目录和文件特定的参数。

警告

• 如果 dirpath 是一个相对路径，在 iterpath() 进行中更改工作目录将导致错误，或者至少结果不准确。

• 将 followlinks 设置为 True 可能会导致无限递归，如果符号链接指向自己的父目录。

# This only returns entries whose names end in ".txt" or equal "foo.png" or
# ".hidden":
iterpath(
    dirpath,
    filter=SelectGlob("*.txt") | SelectNames("foo.png", ".hidden")
)

# Exclude all dot-directories and VCS directories:
iterpath(dirpath, exclude_dirs=SELECT_DOTS | SELECT_VCS_DIRS)

class SelectNames(*names: AnyStr, case_sensitive: bool = True)

class SelectGlob(pattern: AnyStr)

class SelectRegex(pattern: AnyStr | re.Pattern[AnyStr])

SELECT_DOTS

SELECT_VCS

SELECT_VCS_DIRS

SELECT_VCS_FILES