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()	OS固有のキャッシュディレクトリを取得します

基本的な操作

ファイルをダウンロードする

# 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を解凍します

キャッシュの場所

OS	デフォルトのパス
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ハッシュを生成します
• ベースURLとファイルのハッシュを指定してpooch.create()でレジストリを作成します
• 分析スクリプトでREGISTRY.fetch()を使ってファイルを取得します
• 圧縮ファイルにはプロセッサ（Unzip()、Untar()、Decompress()）を追加します
• キャッシュをクリアして再取得し、レジストリをテストします
• 共同作業者向けに、プロジェクトのREADMEにレジストリを記載します

参考資料

• レジストリの設定 - ファイルレジストリを作成、管理します

スクリプト

• scripts/create_registry.py - ローカルファイルからレジストリを生成します