DataLad NEXT扩展

这个DataLad扩展可以被认为是一个额外功能或改进性能和用户体验的临时区域。与其它主题性或更实验性的扩展不同，这里的重点是具有广泛适用性的功能。这个扩展是其他软件包的合适依赖项，这些软件包旨在构建在这个改进的功能集合上。

安装

# create and enter a new virtual environment (optional)
$ virtualenv --python=python3 ~/env/dl-next
$ . ~/env/dl-next/bin/activate
# install from PyPi
$ python -m pip install datalad-next

如何使用

此扩展提供的附加命令在安装后立即可用。但是，为了充分利用所有改进，必须通过执行来启用扩展的自动加载，以便它也能改变核心DataLad包及其命令的行为。

git config --global --add datalad.extensions.load next

这样做将使扩展能够更改核心DataLad包及其命令的行为。

此扩展提供功能的摘要

• 一个用于处理凭据的替代子系统，能够处理为标记秘密的任意属性，并在最小化可避免的用户交互的同时，促进确定合适的凭据，而不会牺牲可配置性。提供了一个方便的方法，实现了获取凭据的标准工作流程。
• 一个面向用户的credentials命令，用于设置、删除和查询凭据。
• 为GitHub、GIN、GOGS、Gitea等平台提供的create-sibling-...命令配备了改进的凭证处理功能，例如，仅在确认凭证有效后才存储输入的凭证，或者在没有指定的情况下自动选择最近使用的匹配凭证。
• 提供create-sibling-webdav命令，通过为Git历史和文件存储配置的兄弟串联在WebDAV服务器上托管数据集。以这种方式在WebDAV上托管的数据集可以使用datalad-clone进行克隆。支持完整的annex设置来存储具有历史文件内容版本的完整数据集，以及用于存储单版本数据集快照的附加模式。后者使得与非使用DataLad的观众方便合作，因为所有文件都可以通过WebDAV服务器的点对点用户界面进行浏览。
• 增强datalad-push以自动将文件导出到配置了exporttree=yes的git-annex特殊远程。
• 当处理非git特殊远程时，加快datalad-push的速度。这特别有利于WebDAV等效率较低的托管场景。
• 增强datalad-siblings enable（AnnexRepo.enable_remote()），以自动部署需要它们的git-annex特殊远程的凭证。
• git-remote-datalad-annex是一个Git远程助手，可以将数据推送到或从任何git-annex特殊远程访问的位置。
• git-annex-backend-XDLRA（最初由mihextras扩展提供）是git-remote-datalad-annex使用的自定义外部git-annex后端。还提供了一个基类，用于在Python中方便地开发外部后端。
• 增强datalad-configuration以支持在没有数据集的情况下从“全局”范围获取配置。
• 新的模块化URL操作框架。该框架直接支持对http(s)、ssh和file URL的操作，并且可以通过自定义功能扩展以支持更多协议或与特定服务器交互。该框架识别基本操作download、upload、delete和stat，并可以实施。该框架提供统一的进度报告和并行内容计算。此框架旨在替代和扩展DataLad核心包中的下载器/提供者框架。与前任相比，它与新的凭证框架集成，并且操作不仅限于下载。
• git-annex-remote-uncurl是一个特殊远程，通过git-annex公开新的URL操作框架。它提供了灵活的方式来组合和重写URL（例如，以补偿存储基础设施的变化），而无需修改记录在数据集中的单个URL。它使得在框架支持的所有服务和协议之间无缝切换。这个特殊远程可以替代DataLad核心包提供的datalad特殊远程。
• 提供download命令作为新模块化URL操作框架的前端。
• 提供与python-requests兼容的认证处理程序（DataladAuth），该处理程序与DataLad的凭证系统接口。
• 提高了DataLad的runner组件（命令执行）的吞吐量。
• 对DataLad的constraints系统进行了大幅度的改进，该系统用于类型转换和参数验证。
• 支持Windows和Mac客户端访问RIA存储。
• 提供next-status命令，比status快得多，并提供了一个mono递归模式，显示嵌套数据集层次结构的修改相对于根数据集的状态。需要Git v2.31（或更高版本）。

DataLad扩展开发的其他功能概述

• 统一的命令参数验证框架。无论使用的API（Python、CLI或GUI）如何，命令参数都进行统一验证。这有助于将参数指定（和验证）与命令的实际实现更严格地分开。后者现在可以仅关注命令的逻辑，而前者可以提供更统一和更全面的验证和错误报告。除了按参数验证和类型转换之外，还支持参数之间的依赖关系验证和值转换。
• 改进可导入功能的组成。命令commands、annexremotes、datasets（等）的关键组件被收集在主题顶级模块中，这些模块在一个地方提供“所有”必要的部件。
• 自动部署本地WebDAV服务器的webdav_server配置。
• HTTP处理工具
  • probe_url()发现HTTP URL的重定向和认证需求
  • get_auth_realm()返回一个认证域的标签，该标签可用于查询匹配的凭据
• 特殊远程凭据管理的工具
  • get_specialremote_credential_properties()检查一个特殊远程并返回查询凭据存储以查找匹配凭据的属性
  • update_specialremote_credential()在成功使用后更新存储中的凭据
  • get_specialremote_credential_envpatch()从凭据返回适合特定特殊远程类型的适当环境“补丁”
• 运行时修补其他datalad代码的辅助工具（《datalad_next.utils.patch》）
• 实现自定义git-annex后端的基类。
• 一组pytest配置以
  • 检查测试是否留下全局配置副作用
  • 检查测试是否留下秘密
  • 提供一个临时配置，该配置与用户环境和其他测试隔离开来
  • 提供一个临时秘密存储库，该存储库与用户环境和其他测试隔离开来
  • 提供一个临时凭证管理器，以执行与用户环境和其他测试隔离开来的凭证部署和操作
• 一个iter_subproc()辅助工具，它允许通过输入/输出可迭代对象与子进程进行通信。
• 一个shell上下文管理器，它允许与（远程）shell交互，包括对上下文中每个shell命令执行输入/输出可迭代对象的支持。

修补DataLad核心包。

上述描述的一些功能依赖于DataLad核心包本身的修改，而不是以附加命令的形式提供。加载此扩展会将一系列补丁应用到datalad包中，以启用它们。当前补丁集的详细描述可在http://docs.datalad.org/projects/next/en/latest/#datalad-patches找到

使用DataLad NEXT进行开发

与核心包相比，此扩展包进展迅速。尽管如此，仍注重API稳定性、适当的语义版本控制和信息丰富的变更日志。

公共API与内部API

可以从datalad_next中的任何子包直接导入的内容被认为是公共API的一部分。对此API的更改确定版本，开发旨在尽可能保持此API的稳定性。这包括签名和返回值行为。

例如：from datalad_next.runners import iter_git_subproc导入公共API的一部分，但from datalad_next.runners.git import iter_git_subproc则不是。

内部API的使用

开发人员显然可以使用非公共API的部分。然而，这应该是在理解这些组件可能从一个版本更改为另一个版本的情况下进行的，没有任何保证的过渡期、弃用警告等。

建议开发人员永远不要重用任何以_（下划线）开头的名称的组件。它们的使用应限制在各自的子包中。

致谢

本DataLad扩展是在德国研究基金会（DFG）的资助下开发的，资助项目为SFB 1451（431549029，INF项目）。

贡献者

Michael Hanke 🐛 💻 🖋 🎨 📖 💵 🔍 🤔 🚇 🚧 🧑‍🏫 📦 📆 👀 📢 ⚠️ 🔧 📓	catetrai 💻 🎨 📖 🤔 ⚠️	Chris Markiewicz 🚧 💻	Michał Szczepanik 🐛 💻 🖋 📖 💡 🤔 🚇 🚧 👀 📢 ⚠️ ✅ 📓	Stephan Heunis 🐛 💻 📖 🤔 🚧 📢 📓	Benjamin Poldrack 🐛 💻	Yaroslav Halchenko 🐛 💻 🚇 🚧 🔧
Christian Mönch 💻 🎨 📖 🤔 👀 ⚠️ 📓	Adina Wagner ️️️️♿️ 🐛 💻 📖 💡 🚧 📆 👀 📢 ⚠️ ✅ 📓	John T. Wodder II 💻 🚇 ⚠️