DataSALad

这是一个纯Python库，包含用于在Git和git-annex附近处理数据的实用工具集合。虽然这是一个从DataLad项目和为DataLad项目构建的基础库，但其实现是独立的，并且意味着可以在DataLad系统外同样良好地使用。

该库的一个重点是高效地与子进程通信，如Git或git-annex命令，这些命令以某种格式读取和生成数据。

以下是一个使用该库可以实现的示例。以下代码通过SSH连接以批处理模式运行git annex find命令来查询远程git-annex仓库。输出以JSON行格式列出并解码为原生Python数据类型。输入和输出都是包含有意义项目的可迭代对象，尽管在较低级别信息作为任意分块的字节流进行传输。

>>> from more_itertools import intersperse
>>> from pprint import pprint
>>> from datasalad.runners import iter_subproc
>>> from datasalad.itertools import (
...     itemize,
...     load_json,
... )

>>> # a bunch of photos we are interested in
>>> interesting = [
...     b'DIY/IMG_20200504_205821.jpg',
...     b'DIY/IMG_20200505_082136.jpg',
... ]

>>> # run `git-annex find` on a remote server in a repository
>>> # that has these photos in the worktree.
>>> with iter_subproc(
...     ['ssh', 'photos@pididdy.local',
...      'git -C "collections" annex find --json --batch'],
...     # the remote process is fed the file names,
...     # and a newline after each one to make git-annex write
...     # a report in JSON-lines format
...     inputs=intersperse(b'\n', interesting),
... ) as remote_annex:
...     # we loop over the output of the remote process.
...     # this is originally a byte stream downloaded in arbitrary
...     # chunks, so we itemize at any newline separator.
...     # each item is then decoded from JSON-lines format to
...     # native datatypes
...     for rec in load_json(itemize(remote_annex, sep=b'\n')):
...         # for this demo we just pretty-print it
...         pprint(rec)
{'backend': 'SHA256E',
 'bytesize': '3357612',
 'error-messages': [],
 'file': 'DIY/IMG_20200504_205821.jpg',
 'hashdirlower': '853/12f/',
 'hashdirmixed': '65/qp/',
 'humansize': '3.36 MB',
 'key': 'SHA256E-s3357612--700a52971714c2707c2de975f6015ca14d1a4cdbbf01e43d73951c45cd58c176.jpg',
 'keyname': '700a52971714c2707c2de975f6015ca14d1a4cdbbf01e43d73951c45cd58c176.jpg',
 'mtime': 'unknown'}
{'backend': 'SHA256E',
 'bytesize': '3284291',
 ...

使用datasalad进行开发

API稳定性非常重要，就像充足的语义版本和有信息量的变更日志一样。

公开API与内部API

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

例如：from datasalad.runners import iter_git_subproc导入了公开API的一部分，但from datasalad.runners.git import iter_git_subproc则没有。

内部API的使用

开发者显然可以使用非公开API的部分。然而，这应该只在没有保证过渡期、弃用警告等的情况下进行。

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

贡献

欢迎对此库做出贡献！有关潜在贡献的范围和风格，请参阅贡献指南。