fetch-data

从 URL 获取数据文件，但仅在需要时。通过 SHA256 验证内容。一些 Python Pooch 兼容性。

Fetch-Data 检查本地数据目录，然后下载所需的文件。它始终通过哈希验证本地文件和下载的文件。

Fetch-Data 使下载大文件和小文件变得简单。例如，这里我们从 GitHub 下载一个基因组文件（如果尚未下载）。然后我们打印现在本地文件的大小。

use fetch_data::sample_file;

let path = sample_file("small.fam")?;
println!("{}", std::fs::metadata(path)?.len()); // Prints 85

# Ok::<(), anyhow::Error>(())

功能

• 线程安全 -- 允许与 Rust 的多线程测试框架一起使用。
• 受到 Python 流行 Pooch 和我们的 PySnpTools filecache 模块 的启发。
• 避免使用 Tokio 等运行时（通过使用 ureq 通过阻塞 I/O 下载文件）。

建议用法

您可以以多种方式设置 FetchData。以下是一个设置的步骤，以及相应的示例代码。

• 创建一个包含空格分隔的文件和其哈希值的列表的 registry.txt 文件。（这与 Pooch 的格式相同。有关创建此文件的提示，请参阅 Registry Creation 部分。）

• 如下所示，创建一个全局静态的 FetchData 实例，该实例读取您的 registry.txt 文件。给它

  • 文件下载的 URL 根目录
  • 一个环境变量，告诉存储文件的本地数据目录
  • 一个 qualifier、organization 和 application -- 当环境变量未设置时，用于创建本地数据目录。有关详细信息，请参阅 crate ProjectsDir。

• 如下所示，定义一个公共函数 sample_file，该函数接收一个文件名，并返回一个包含下载文件路径的 Result。

use fetch_data::{ctor, FetchData, FetchDataError};
use std::path::{Path, PathBuf};

#[ctor]
static STATIC_FETCH_DATA: FetchData = FetchData::new(
    include_str!("../registry.txt"),
    "https://raw.githubusercontent.com/CarlKCarlK/fetch-data/main/tests/data/",
    "BAR_APP_DATA_DIR", // env_key
    "com",              // qualifier
    "Foo Corp",         // organization
    "Bar App",          // application
);

/// Download a data file.
pub fn sample_file<P: AsRef<Path>>(path: P) -> Result<PathBuf, Box<FetchDataError>> {
    STATIC_FETCH_DATA.fetch_file(path)
}

现在您可以按照需要使用您的 sample_file 函数下载文件。

注册表创建

您可以通过多种方式创建您的 registry.txt 文件。以下是一个创建注册表的步骤示例，以及相应的示例代码。

• 将您的数据文件上传到互联网。
  • 例如，Fetch-Data 将其示例数据文件放在 tests/data 目录中，因此它们上传到 这个GitHub文件夹。在GitHub中，通过查看 数据文件的原始视图，我们可以看到这些文件的根URL。在 cargo.toml 中，我们通过 exclude = ["tests/data/*"] 将这些数据文件排除在我们的crate之外。
• 如下所示，编写代码：
  • 创建一个没有注册表内容的 FetchData 实例。
  • 列出您的数据目录中的文件。
  • 在您的文件列表上调用 gen_registry_contents 方法。此方法将下载文件，计算它们的哈希值，并创建一个包含文件名和哈希值的字符串。
• 打印此字符串，然后手动将其粘贴到名为 registry.txt 的文件中。

use fetch_data::{FetchData, dir_to_file_list};

let fetch_data = FetchData::new(
    "", // registry_contents ignored
    "https://raw.githubusercontent.com/CarlKCarlK/fetch-data/main/tests/data/",
    "BAR_APP_DATA_DIR", // env_key
    "com",              // qualifier
    "Foo Corp",         // organization
    "Bar App",          // application
);
let file_list = dir_to_file_list("tests/data")?;
let registry_contents = fetch_data.gen_registry_contents(file_list)?;
println!("{registry_contents}");

# use fetch_data::FetchDataError; // '#' needed for doctest
# Ok::<(), Box<FetchDataError>>(())

注意

• 欢迎提出功能请求和贡献。

• 不要使用我们的示例 sample_file。定义您自己的 sample_file，使其知道在哪里找到 您 的数据文件。

• FetchData 实例不必是全局和静态的。请参阅 FetchData::new 中的非全局实例示例。

• FetchData 实例的额外 方法 可以一次性下载多个文件，并可以提供本地数据目录的路径。

• 您不需要使用 registry.txt 文件和 FetchData 实例。您可以使用独立的函数 fetch 来检索具有已知URL、哈希和本地路径的单个文件。

• 额外的独立函数可以下载文件并计算文件的哈希值。

• Fetch-Data 总是进行二进制下载，以保持跨操作系统的行结束一致性。

• 基因组学crate Bed-Reader 使用 Fetch-Data。

• 为了让 FetchData 作为静态全局变量良好工作，FetchData::new 从不失败。相反，FetchData 会存储任何错误，并在第一次调用 fetch_file 等，时返回它。

• 在Windows下调试此crate可能会引发“Oops! 调试适配器异常终止”异常。这是ureq通过的一种LLVM、Windows、NVIDIA(?)问题。

• 此crate遵循来自《Towards Data Science》的《优雅Rust库API的九条规则》。

项目链接

• 安装
• 文档
• 源代码
• 讨论
• 错误报告和功能请求