LoaderAdapter

LoaderAdapter 處理資料載入，並自動處理 benchmark:// 協定以下載基準資料集和模式檔案。

類別架構

classDiagram

    class LoaderAdapter {
        +config: dict
        +loader: Loader
        +benchmarker: Benchmarker
        +__init__(config)
        +run() tuple[DataFrame, Schema]
        -_handle_benchmark_protocol()
        -_init_loader()
    }

    class Loader {
        +filepath: str
        +schema: Schema
        +load() tuple[DataFrame, Schema]
    }

    class Benchmarker {
        +config: BenchmarkerConfig
        +download()
        +get_filepath()
    }

    class BenchmarkerConfig {
        +benchmark_name: str
        +filepath_raw: str
    }

    class BenchmarkerRequests {
        +download()
    }

    LoaderAdapter ..> Loader : 用於資料載入
    LoaderAdapter ..> Benchmarker : 用於基準協定
    Benchmarker --> BenchmarkerConfig : 擁有
    Benchmarker ..> BenchmarkerRequests : 創建

    %% 樣式定義
    class LoaderAdapter {
        <<主要類別>>
    }
    style LoaderAdapter fill:#E6E6FA

    class Loader {
        <<核心模組>>
    }
    style Loader fill:#4169E1,color:#fff

    class Benchmarker {
        <<基準處理器>>
    }
    style Benchmarker fill:#9370DB,color:#fff

    style BenchmarkerConfig fill:#FFE4E1
    style BenchmarkerRequests fill:#FFE4E1

    note for LoaderAdapter "1. 偵測 benchmark:// 協定\n2. 使用 Benchmarker 下載\n3. 使用本地路徑的 Loader"

圖例：

• 淺紫色框：LoaderAdapter 主類別
• 藍色框：核心載入模組
• 紫色框：基準資料集處理模組
• 淺粉色框：配置類別
• ..>：依賴關係
• -->：擁有關係

主要功能

• 統一的資料載入介面
• 自動偵測並處理資料和模式的 benchmark:// 協定
• 整合 Loader 與 Benchmarker 功能
• 回傳資料和 Schema 詮釋資料
• 支援 CSV 資料檔和 YAML 模式檔

方法參考

__init__(config: dict)

初始化 LoaderAdapter 實例，自動處理 benchmark:// 協定。

參數：

• config：dict，必要
  • 配置參數字典
  • 必須包含 filepath 鍵
  • 支援 benchmark:// 協定
  • 可選參數包括：
    • schema：Schema 檔案路徑
    • nrows：僅載入指定數量的資料列（用於快速測試）
    • delimiter、encoding、header 等 pandas 讀取參數

run(input: dict)

執行資料載入，包括自動下載基準資料集。

參數：

• input：dict，必要
  • 輸入參數字典
  • LoaderAdapter 通常接收空字典 {}

回傳： 無直接回傳值。使用 get_result() 和 get_metadata() 取得結果。

get_result()

取得載入的資料。

回傳：

• pd.DataFrame：載入的資料

get_metadata()

取得資料的 Schema 詮釋資料。

回傳：

• Schema：資料詮釋資料

使用範例

from petsard.adapter import LoaderAdapter

# 一般檔案載入
adapter = LoaderAdapter({
    "filepath": "data/users.csv",
    "schema": "schemas/user.yaml"
})

# 使用 nrows 參數進行快速測試
adapter = LoaderAdapter({
    "filepath": "data/large_dataset.csv",
    "schema": "schemas/data.yaml",
    "nrows": 1000  # 僅載入前 1000 列
})

# 或使用 benchmark:// 協定
# adapter = LoaderAdapter({
#     "filepath": "benchmark://adult-income",
#     "schema": "benchmark://adult-income_schema"
# })

# 執行載入
adapter.run({})

# 取得結果
data = adapter.get_result()
metadata = adapter.get_metadata()

工作流程

1. 協定偵測：檢查 filepath/schema 是否使用 benchmark:// 協定
2. Benchmarker 處理（基準協定時）
   • 下載檔案到本地
   • 驗證 SHA-256（不符時發出警告）
   • 轉換路徑為本地路徑
3. 資料載入：載入資料和詮釋資料

注意事項

• 這是內部 API，不建議直接使用
• 建議使用 YAML 配置檔和 Executor
• 基準檔案在首次下載後會快取
• 結果會快取直到下次 run() 呼叫