Glob-like path matching with {} capture groups

These details have not been verified by PyPI

Project description

path_walker

一个支持 {} 捕获组的路径匹配库。用法类似 glob，但 {} 标记的部分会被提取并返回，而不是仅用于过滤。

安装

pip install -e .

快速开始

from path_walker import walk, walk_first

模式语法

语法	含义
`*`	匹配单个路径段（不跨越 `/`）
`**`	匹配零或多个路径段（可跨越 `/`）
`?`	匹配单个字符（不跨越 `/`）
`{P}`	捕获组：匹配模式 `P`，将匹配到的内容作为结果返回

{P} 内部同样支持 *、**、? 以及字面量，且可以包含 /（跨目录捕获）。

返回值规则

捕获组数量决定返回值的形状：

`{}` 数量	返回类型	说明
0	`list[str]`	所有匹配的完整路径
1	`list[str]`	每个匹配的捕获内容
2+	`list[list[str]]`	每个匹配的所有捕获内容（2D）

使用示例

查找包含指定文件的目录

# 找出所有直接包含 image.jpg 的目录名
walk('/photos/{*}/image.jpg')
# -> ['2023', '2024']

多级捕获

# 找出 data/ 下所有形如 */bbb 的子路径
walk('./data/{*/bbb}')
# -> ['a/bbb', 'b/bbb']

{*/bbb} 是一个跨两级目录的捕获组，匹配 任意名称/bbb 并将整段作为结果返回。

2D 结果（多个捕获组）

# 同时捕获 子目录名 和 文件名（不含扩展名）
walk('/photos/{*}/{*}.jpg')
# -> [['2023', 'holiday'], ['2023', 'beach'], ['2024', 'sunset']]

内联捕获组

捕获组可以嵌在文件名中间，而不必占据整个路径段：

# {c} 只匹配字面量 'c'，文件必须叫 abc.png
walk('/{*}/ab{c}.png')
# -> [['photos', 'c'], ['raw', 'c']]

# {z.png} 匹配字面量 'z.png'（. 被转义）
walk('/{*}/ababa/{z.png}')
# -> [['art', 'z.png'], ['raw', 'z.png']]

无捕获组（纯过滤）

# 返回完整路径列表
walk('./docs/*.pdf')
# -> ['/abs/path/to/docs/report.pdf']

`**` 跨多级搜索

# 找出任意深度下所有 .jpg 文件，捕获文件名（不含扩展名）
walk('./root/**/{*}.jpg')
# -> ['holiday', 'beach', 'sunset', 'image']

`walk_first`

# 返回第一个匹配，没有则返回 None
walk_first('./docs/{*}.pdf')
# -> 'report'

API

`walk(pattern, *, root=None)`

遍历文件系统，返回所有匹配 pattern 的结果。

参数

pattern — 路径模式，支持绝对路径和相对路径。
root — 可选，覆盖遍历起始目录。默认从 pattern 的字面量前缀自动推断。

返回值 — 见返回值规则。

`walk_first(pattern, *, root=None)`

返回第一个匹配结果，没有匹配则返回 None。

捕获组详解

`{}` 内的 `*` 与 `**`

写法	匹配
`{*}`	一个路径段（不含 `/`）
`{**}`	一或多个字符（含 `/`，可跨多级）
`{*/sub}`	任意一级目录 + `/sub`
`{**.log}`	任意路径结尾为 `.log`

`{}` 内的字面量

{} 内部所有非通配符字符均视为字面量（包括 .）：

{z.png}   匹配且只匹配文件名 z.png
{c}       匹配且只匹配字符 c
{ab{c}d}  不支持嵌套 {}

Windows 路径说明

path_walker 在内部统一使用 / 作为路径分隔符。

输入 pattern：/ 和 \\ 均可，库会自动转换。

walk('C:/Users/Kevin/{*}/image.jpg')      # ✓
walk('C:\\Users\\Kevin\\{*}\\image.jpg')  # ✓ 等价

输出结果：无论运行在何种平台，返回值始终使用 /。

# 1 个捕获组 -> 捕获内容本身，不含分隔符
walk('C:/Users/{*}/image.jpg')
# -> ['Kevin']

# 0 个捕获组 -> 完整路径，用 / 分隔（非 \）
walk('C:/Users/Kevin/docs/*.pdf')
# -> ['C:/Users/Kevin/docs/report.pdf']

项目结构

path_walker/
  path_walker/
    __init__.py   # 导出 walk, walk_first
    pattern.py    # 模式解析与正则转换
    walker.py     # 文件系统遍历逻辑
  tests/
    test_pattern.py
    test_walker.py
  pyproject.toml

运行测试

pip install pytest
pytest tests/

许可证

GNU Lesser General Public License v2.1

闭源项目可以 import 并使用本库 ✅
修改本库代码必须以 LGPL-2.1 开源 ✅
必须保留原作者署名 ✅

Project details

These details have not been verified by PyPI

Release history Release notifications | RSS feed

This version

0.1.0

Mar 24, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kevinzonda_path_walker-0.1.0.tar.gz (32.7 kB view details)

Uploaded Mar 24, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

kevinzonda_path_walker-0.1.0-py3-none-any.whl (26.3 kB view details)

Uploaded Mar 24, 2026 Python 3

File details

Details for the file kevinzonda_path_walker-0.1.0.tar.gz.

File metadata

Download URL: kevinzonda_path_walker-0.1.0.tar.gz
Upload date: Mar 24, 2026
Size: 32.7 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for kevinzonda_path_walker-0.1.0.tar.gz
Algorithm	Hash digest
SHA256	`179b4cdf3147667191550b33e2f217bf6e105be8d0611b60b9f69a6ffb0fffa8`
MD5	`6f2a2fe2f0a01f56250082a5f3a7fd4e`
BLAKE2b-256	`898a11785c43cff83b57841e4cdb88f599a43aa2ac9c5af82b17a69fca59ba90`

See more details on using hashes here.

Provenance

The following attestation bundles were made for kevinzonda_path_walker-0.1.0.tar.gz:

Publisher: publish.yml on KevinZonda/path_walker

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: kevinzonda_path_walker-0.1.0.tar.gz
- Subject digest: 179b4cdf3147667191550b33e2f217bf6e105be8d0611b60b9f69a6ffb0fffa8
- Sigstore transparency entry: 1171226142
- Sigstore integration time: Mar 24, 2026
Source repository:
- Permalink: KevinZonda/path_walker@114a1ee2b34f1c76ebe22f22def50e17a5787758
- Branch / Tag: refs/tags/0.1.0
- Owner: https://github.com/KevinZonda
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@114a1ee2b34f1c76ebe22f22def50e17a5787758
- Trigger Event: release

File details

Details for the file kevinzonda_path_walker-0.1.0-py3-none-any.whl.

File metadata

Download URL: kevinzonda_path_walker-0.1.0-py3-none-any.whl
Upload date: Mar 24, 2026
Size: 26.3 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for kevinzonda_path_walker-0.1.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`8d914b8bc0e9ed68f450e6d7e02b11606b85b8098b74f4ebd01c1d2dbcf0e651`
MD5	`eba7bcca3a2c7083e602ab3b361f715a`
BLAKE2b-256	`60e628c567d396fe2424944545ad8b1ffcf2838c76c23022481887355879b18e`

See more details on using hashes here.

Provenance

The following attestation bundles were made for kevinzonda_path_walker-0.1.0-py3-none-any.whl:

Publisher: publish.yml on KevinZonda/path_walker

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: kevinzonda_path_walker-0.1.0-py3-none-any.whl
- Subject digest: 8d914b8bc0e9ed68f450e6d7e02b11606b85b8098b74f4ebd01c1d2dbcf0e651
- Sigstore transparency entry: 1171226639
- Sigstore integration time: Mar 24, 2026
Source repository:
- Permalink: KevinZonda/path_walker@114a1ee2b34f1c76ebe22f22def50e17a5787758
- Branch / Tag: refs/tags/0.1.0
- Owner: https://github.com/KevinZonda
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@114a1ee2b34f1c76ebe22f22def50e17a5787758
- Trigger Event: release

kevinzonda-path-walker 0.1.0

Navigation

Verified details

Maintainers

Unverified details

Meta

Classifiers

Project description

path_walker

安装

快速开始

模式语法

返回值规则

使用示例

查找包含指定文件的目录

多级捕获

2D 结果（多个捕获组）

内联捕获组

无捕获组（纯过滤）

** 跨多级搜索

walk_first

API

walk(pattern, *, root=None)

walk_first(pattern, *, root=None)

捕获组详解

{} 内的 * 与 **

{} 内的字面量

Windows 路径说明

项目结构

运行测试

许可证

Project details

Verified details

Maintainers

Unverified details

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

`**` 跨多级搜索

`walk_first`

`walk(pattern, *, root=None)`

`walk_first(pattern, *, root=None)`

`{}` 内的 `*` 与 `**`

`{}` 内的字面量