pooch

Pooch - 数据文件获取

快速参考

import pooch

# Download single file
file_path = pooch.retrieve(
    url="https://example.com/data.csv",
    known_hash="sha256:abc123...",  # None to skip verification
    fname="data.csv",
    path=pooch.os_cache("myproject")
)

# Create registry for multiple files
REGISTRY = pooch.create(
    path=pooch.os_cache("myproject"),
    base_url="https://example.com/data/",
    registry={"data.csv": "sha256:abc123...", "model.nc": "sha256:def456..."}
)
data_file = REGISTRY.fetch("data.csv")

# Generate hash for local file
file_hash = pooch.file_hash("/path/to/file.csv")

主要函数

函数	用途
pooch.retrieve()	下载单个文件并缓存
pooch.create()	创建自定义数据注册表
pooch.file_hash()	生成文件的 SHA256/MD5 哈希值
pooch.os_cache()	获取操作系统专用的缓存目录

基本操作

下载文件

# With hash verification
file_path = pooch.retrieve(
    url="https://example.com/data.nc",
    known_hash="sha256:abc123..."
)

# Without verification (development only)
file_path = pooch.retrieve(url="https://example.com/data.nc", known_hash=None)

# From Zenodo DOI
file_path = pooch.retrieve(
    url="doi:10.5281/zenodo.1234567/data.zip",
    known_hash="sha256:abc123..."
)

解压归档文件

# ZIP archive
files = pooch.retrieve(
    url="https://example.com/data.zip",
    known_hash="sha256:abc123...",
    processor=pooch.Unzip()
)

# Decompress single gzip file
file_path = pooch.retrieve(
    url="https://example.com/data.csv.gz",
    known_hash="sha256:abc123...",
    processor=pooch.Decompress(name="data.csv")
)

其他选项

# Progress bar for large downloads
file_path = pooch.retrieve(url=url, known_hash=hash, progressbar=True)

# HTTP authentication
file_path = pooch.retrieve(
    url="https://example.com/protected/data.csv",
    known_hash=None,
    downloader=pooch.HTTPDownloader(auth=("user", "pass"))
)

处理器选项

处理器	用途
Unzip()	解压 ZIP 归档文件
Untar()	解压 TAR/TAR.GZ 归档文件
Decompress()	解压 gzip、bz2、lzma、xz 文件

缓存位置

操作系统	默认路径
Linux	~/.cache/<project>
macOS	~/Library/Caches/<project>
Windows	C:\Users\<user>\AppData\Local\<project>\Cache

错误处理

try:
    file_path = pooch.retrieve(url=url, known_hash=hash)
except pooch.exceptions.HTTPDownloadError:
    print("Download failed - check URL")
except pooch.exceptions.DownloadError:
    print("Network issue")

与替代方案的适用场景对比

工具	最适合的场景	局限性
pooch	可复现的数据下载、哈希校验、缓存	不是版本控制系统
urllib/requests	简单的一次性下载、自定义 HTTP 逻辑	不支持缓存和哈希校验
DVC	与 git 配合进行数据版本控制	设置较复杂，需要远程存储
wget	快速命令行下载	不支持 Python 集成，也没有缓存逻辑

在以下情况下使用 pooch： 你需要可复现的数据下载，并进行自动缓存和完整性校验，尤其适用于科学数据注册表。

在以下情况下考虑替代方案： 你需要与 git 集成的完整数据版本控制（使用 DVC）、无需缓存的简单一次性下载（使用 requests），或命令行批量下载（使用 wget）。

常见工作流

使用注册表设置可复现的数据下载

• 确定所有必需数据文件及其 URL
• 使用 pooch.file_hash() 为每个文件生成 SHA256 哈希值
• 使用 pooch.create() 创建注册表，并指定基础 URL 和文件哈希值
• 在分析脚本中使用 REGISTRY.fetch() 获取文件
• 为压缩文件添加处理器（Unzip()、Untar()、Decompress()）
• 清除缓存并重新获取文件，以测试注册表
• 在项目 README 中记录注册表信息，供协作者参考

参考资料

• 注册表配置 - 创建和管理文件注册表

脚本

• scripts/create_registry.py - 根据本地文件生成注册表