hansel 2.0.1

快速介绍

想象这个文件夹树

data
└── raw
    ├── 0040000
    │   └── session_1
    │       ├── anat_1
    │       └── rest_1
    ├── 0040001
    │   └── session_1
    │       ├── anat_1
    │       └── rest_1
    ├── 0040002
    │   └── session_1
    │       ├── anat_1
    │       └── rest_1
    ├── 0040003
    │   └── session_1
    │       ├── anat_1
    │       └── rest_1
    ├── 0040004
    │   └── session_1
    │       ├── anat_1
    │       └── rest_1

>>> from pprint import pprint
>>> from hansel import Crumb

# create the crumb
>>> crumb = Crumb("{base_dir}/raw/{subject_id}/{session_id}/{image_type}/{image}")

# set the base_dir path
>>> crumb = crumb.replace(base_dir='/tmp/hansel/data')
>>> print(str(crumb))
/tmp/hansel/data/raw/{subject_id}/{session_id}/{image_type}/{image}

# get the ids of the subjects
>>> subj_ids = crumb['subject_id']
>>> print(subj_ids)
['0040000', '0040001', '0040002', '0040003', '0040004', '0040005', ...

# get the paths to the subject folders, the output can be strings or crumbs,
# you choose with the ``make_crumbs`` boolean argument. Default: True.
>>> subj_paths = crumb.ls('subject_id', make_crumbs=True)
>>> pprint(subj_paths)
[Crumb("/tmp/hansel/data/raw/0040000/{session_id}/{image_type}/{image}"),
 Crumb("/tmp/hansel/data/raw/0040001/{session_id}/{image_type}/{image}"),
 Crumb("/tmp/hansel/data/raw/0040002/{session_id}/{image_type}/{image}"),
 Crumb("/tmp/hansel/data/raw/0040003/{session_id}/{image_type}/{image}"),
 Crumb("/tmp/hansel/data/raw/0040004/{session_id}/{image_type}/{image}"),
 ...

# set the image_type
>>> anat_crumb = crumb.replace(image_type='anat_1')
>>> print(anat_crumb)
/tmp/hansel/data/raw/{subject_id}/{session_id}/anat_1/{image}

# get the paths to the images inside the anat_1 folders
>>> anat_paths = anat_crumb.ls('image')
>>> pprint(anat_paths)
[Crumb("/tmp/hansel/data/raw/0040000/session_1/anat_1/mprage.nii.gz"),
 Crumb("/tmp/hansel/data/raw/0040001/session_1/anat_1/mprage.nii.gz"),
 Crumb("/tmp/hansel/data/raw/0040002/session_1/anat_1/mprage.nii.gz"),
 Crumb("/tmp/hansel/data/raw/0040003/session_1/anat_1/mprage.nii.gz"),
 Crumb("/tmp/hansel/data/raw/0040004/session_1/anat_1/mprage.nii.gz"),
 ...

# get the ``session_id`` of each of these ``anat_paths``
>>> sessions = [cr['session_id'][0] for cr in anat_paths]
>>> print(sessions)
['session_1', 'session_1', 'session_1', 'session_1', 'session_1', ...

# if you don't want the the output to be ``Crumbs`` but string paths:
>>> anat_paths = anat_crumb.ls('image', make_crumbs=False)
>>> pprint(anat_paths)
['/tmp/hansel/data/raw/0040000/session_1/anat_1/mprage.nii.gz',
 '/tmp/hansel/data/raw/0040001/session_1/anat_1/mprage.nii.gz',
 '/tmp/hansel/data/raw/0040002/session_1/anat_1/mprage.nii.gz',
 '/tmp/hansel/data/raw/0040003/session_1/anat_1/mprage.nii.gz',
 '/tmp/hansel/data/raw/0040004/session_1/anat_1/mprage.nii.gz',
 ...

# you can also use a list of ``fnmatch`` expressions to ignore certain files patterns
# using the ``ignore_list`` argument in the constructor.
# For example, the files that start with '.'.
>>> crumb = Crumb("{base_dir}/data/raw/{subject_id}/{session_id}/{image_type}/{image}", ignore_list=['.*'])

一旦你有一个完全定义的Crumb，你可以使用它的path来对相应的文件进行操作。为此，你必须通过使用str(crumb)或crumb.path将其转换为字符串。

在查看长介绍之后，请查看更多快速示例，并查看更多功能和技巧。

长介绍

我经常遇到与结构化文件夹路径相关的工作，就像上面显示的那样。

我尝试了许多解决这些情况的方法：循环、字典、配置文件等。我总是反复为同一个问题做不同的事情。

这周我厌倦了这种情况，决定将结构化文件夹树表示为一个字符串，并最简单地访问它。

如果你查看上面的文件夹结构，我有

• 挂载的根目录：...data/raw，

• 许多标识符（在这种情况下是主题标识），例如，0040000，

• 会话标识，session_1和

• 数据类型（在这种情况下为图像类型），anat_1 和 rest_1。

使用 hansel，我可以这样表示文件夹结构

>>> from hansel import Crumb
>>> crumb = Crumb("{base_dir}/data/raw/{subject_id}/{session_id}/{image_type}/{image}")

假设我们有一个基础目录 /home/hansel/ 下挂载的上述结构。

我可以使用 replace 函数来设置 base_dir 参数

>>> crumb = crumb.replace(base_dir='/home/hansel')
>>> print(str(crumb))
/home/hansel/data/raw/{subject_id}/{session_id}/{image_type}/{image}

如果我不需要 crumb 的副本，我可以使用 [] 操作符

>>> crumb['base_dir'] = '/tmp/hansel'
>>> print(str(crumb))
/tmp/hansel/data/raw/{subject_id}/{session_id}/{image_type}/{image}

现在，我的数据集的根路径已经设置，我可以开始查询我的 crumb 路径。

如果我想知道现有 subject_id 文件夹的路径

我们可以使用 ls 函数。它的输出可以是 str 或 Crumb。我可以使用 make_crumbs 参数来选择这个（默认：True）

>>> subj_crumbs = crumb.ls('subject_id')
>>> pprint(subj_crumbs)
[Crumb("/tmp/hansel/data/raw/0040000/{session_id}/{image_type}/{image}"),
 Crumb("/tmp/hansel/data/raw/0040001/{session_id}/{image_type}/{image}"),
 Crumb("/tmp/hansel/data/raw/0040002/{session_id}/{image_type}/{image}"),
 Crumb("/tmp/hansel/data/raw/0040003/{session_id}/{image_type}/{image}"),
 Crumb("/tmp/hansel/data/raw/0040004/{session_id}/{image_type}/{image}"),
 ...

>>> subj_paths = crumb.ls('subject_id', make_crumbs=False)
>>> pprint(subj_paths)
['/tmp/hansel/data/raw/0040000/{session_id}/{image_type}/{image}',
 '/tmp/hansel/data/raw/0040001/{session_id}/{image_type}/{image}',
 '/tmp/hansel/data/raw/0040002/{session_id}/{image_type}/{image}',
 '/tmp/hansel/data/raw/0040003/{session_id}/{image_type}/{image}',
 '/tmp/hansel/data/raw/0040004/{session_id}/{image_type}/{image}',
 ...

如果我想知道现有的 subject_id

>>> subj_ids = crumb.ls('subject_id', fullpath=False)
>>> print(subj_ids)
['0040000', '0040001', '0040002', '0040003', '0040004', '0040005', ...

或

>>> subj_ids = crumb['subject_id']
>>> print(subj_ids)
['0040000', '0040001', '0040002', '0040003', '0040004', '0040005', ...

现在，如果我想获取 anat_1 文件夹内所有图像的路径，我可以这样做

>>> anat_crumb = crumb.replace(image_type='anat_1')
>>> print(anat_crumb)
/tmp/hansel/data/raw/{subject_id}/{session_id}/anat_1/{image}

或者如果我不需要保留 crumb 的副本

>>> crumb['image_type'] = 'anat_1'

# get the paths to the images inside the anat_1 folders
>>> anat_paths = crumb.ls('image')
>>> pprint(anat_paths)
[Crumb("/tmp/hansel/data/raw/0040000/session_1/anat_1/mprage.nii.gz"),
 Crumb("/tmp/hansel/data/raw/0040001/session_1/anat_1/mprage.nii.gz"),
 Crumb("/tmp/hansel/data/raw/0040002/session_1/anat_1/mprage.nii.gz"),
 Crumb("/tmp/hansel/data/raw/0040003/session_1/anat_1/mprage.nii.gz"),
 Crumb("/tmp/hansel/data/raw/0040004/session_1/anat_1/mprage.nii.gz"),
 ...

记住，我仍然可以在 anat_paths 的前一个 crumbs 中访问被替换的 crumb 参数。

>>> subj_ids = [cr['subject_id'][0] for cr in anat_paths]
>>> print(subj_ids)
['0040000', '0040001', '0040002', '0040003', '0040004', ...

>>> files = [cr['image'][0] for cr in anat_paths]
>>> print(files)
['mprage.nii.gz', 'mprage.nii.gz', 'mprage.nii.gz', 'mprage.nii.gz', ...

更多功能和技巧

还有更多可能性，例如

代码

Github

您可以使用以下命令检查最新源代码：

git clone https://www.github.com/alexsavio/hansel.git

或者如果您具有写入权限

git clone git@github.com:alexsavio/hansel.git

如果您打算为此项目创建补丁，请从主分支创建一个分支。

我们在仓库中用版本号标记稳定版本。

测试

我们正在使用 py.test 帮助我们进行测试。

否则，您可以执行以下命令来运行测试：

python setup.py test

或

py.test

或

make test

版本 2.0.1 (25.02.2018)

• 在整个代码库中添加类型注解。

• 修复了文档。现在 README 中的示例代码片段已经过测试。

版本 2.0.0 (24.02.2018)

• 弃用 Python 2.7。添加对 Python 3.6 的支持。

版本 1.0.0 - 版本 1.0.2

• 将 CLI 文档添加到 README 中。

• 在 ls 函数中将 make_crumbs 设置为 False，如果 fullpath 也为 False。

• 当 fullpath 为 False 时，在 ls 函数中强制 arg_name 参数为必填项。

版本 0.9.0 - 0.9.6

• “cli diff” 和 “cli intersect” 有相同的接口。

• 更改了“cli intersect”打印结果的方式。添加了‘base_crumb’选项。

• 将 crumb 添加到 CLI 默认忽略列表中: [‘.*’]。

• 将 crumb diff 添加到 CLI。

• 添加了带测试的 difference 实用函数。

• 将 test__utils.py 添加为 WIP。

• 将 CLI 移动到 click。

• 修复了令人讨厌的 bug。

• 添加 crumb_copy。

• 现在它不会关心相对路径。

• 修复 crumb_copy 以处理现有路径和链接相对路径。

• 添加 crumb_copy CLI。

• 将 click 添加为依赖项，并将 crumb_copy 移动到 crumb copy。

• 添加 crumb ls 和 crumb intersect CLI。

• 将 is_crumb_arg 函数添加到 utils。

• 修复 crumb copy 参数名称中的错误。

版本 0.8.0 - 0.8.3

• 将 Crumb.ls 函数中 check_exists 的默认值设置为 True。我认为没有人会对不存在的路径感兴趣。

• 现在您可以为 Crumb 设置一个非开放项，即我可以替换已设置的 crumb 参数的值。

• 更新 README.rst

• 代码清理。

• 在 valuesmap_to_dict 函数中将 dict 替换为 OrderedDict 输出。

• 在 ls 和 __get_item__ 的 arg_name 参数中添加正则表达式选项。

版本 0.7.0 - 0.7.5

• 重构了 Crumb 的工作方式，现在使用 string.Formatter。这将有助于新的功能，因为逻辑更简单。现在不可能更改 Crumbs 的语法，尽管我认为没有人会对这个感兴趣。

• 修复了前几个版本的一些错误。

• 现在 copy 方法不再是类方法，因此您也可以使用 crumb.copy() 以及 Crumb.copy(crumb)。

• patterns 已不再是一个字典，正则表达式已嵌入到 _path 字符串中。属性 patterns 返回与之前相同的字典。必须使用函数 set_pattern 来设置给定参数的不同模式。

• 更新 README.rst

• 修复了 README.rst 文件，因为 PyPI 的语法错误。

• 修复了 Python 2.7 的错误。

• 修复了 .rst 文件中的错误，以纠正 PyPI 中的 restview。

• 代码清理。

版本 0.6.0 - 0.6.2

• 在 utils.py 中添加了 intersection 函数。

• __getitem__ 的行为有所改变，现在它即使在只有一个从 _argval 替换的字符串时也返回一个值列表。

• 对 Crumbs 中的私有函数进行了通用重命名，使其更符合 open_args/all_args 概念。

• 修复了一些错误，现在从 unfold 和 ls 生成的面包屑将具有与原始 Crumb 相同的参数。

• 当 len(arg_names) == 1 时，更改了 intersection 的行为，以提高与 crumb.build_path 函数的兼容性。

• 改进了 README，并添加了使用 intersection 的新示例。

• 添加了 pandas 辅助函数。

• 添加了将值映射转换为字典的 utils。

• 改进了文档字符串。

版本 0.5.0 - 0.5.5

• 添加了 Python 2.7 兼容性。朋友们不要让朋友们使用 Python 2.7！

• 在构造函数中添加了 regex 参数的 ‘re.ignorecase’ 选项。

• 添加了 utils.check_path 函数。

• 修复了 Crumb.split 函数，使其返回面包屑的未定义部分。

• 添加了 Crumbs.keys() 函数。

• 将 utils.remove_duplicates() 重命名为 utils.rm_dups()。

• 弃用 Crumbs.keys() 函数。

• 将 Crumbs.keys() 重命名为 Crumbs.open_args() 并添加了 Crumbs.all_args()。

• 将 Crumbs 的内部逻辑替换为使用 Crumbs.open_args()，使其更快。

• 将 CHANGES.rst 添加到 MANIFEST.in 中。

版本 0.4.0 - 0.4.2

• 填充 CHANGES.rst。

• Crumb.ls 函数的所有输出都将排序。

• 为面包屑参数添加正则表达式或 fnmatch 选项。

• 更改 exists 的行为。现在空面包屑参数在 exist() 时将返回 False。

• 代码清理。

• 修复错误。

• 修复 CHANGES.rst 以纠正 PyPI 中的 restview。

• 感谢 restview: https://pypi.python.org/pypi/restview。使用：restview --long-description

• 改进了 README 中的文档。

• 将成员 _argreg 重命名为 patterns，以便用户可以使用它来管理参数模式。

版本 0.3.0 - 0.3.1

• 添加了 _argval 成员，这是一个字典，用于存储面包屑参数的替换。

• 添加了测试。

• 从 Crumb.ls 函数中删除了 rm_dups 选项。

• 从 Crumb 中删除了当没有面包屑参数时的 Paths 转换。

• 修复了 README。

• 代码清理。

版本 0.2.0

• 在 Crumb 构造函数中添加了 ignore_list 参数。

版本 0.1.0 - 0.1.1

• 简化了代码。

• 增加了测试覆盖率。

• 将 exist_check 添加到 Crumb.ls 函数。

• 修复错误。

• 添加了 Crumb.unfold 函数。

• 将 mktree 从 Crumb 类中移出。