validkit-py 1.0.1

A simple and powerful validation library for Python.

ValidKit

ValidKit は、辞書ベースで簡潔に定義でき、日本語キーや複雑なネストに対応した Python バリデーションライブラリです。Pydantic より軽量で、Discord ボットの設定管理や設定ファイルの検証など、実用的かつ再現性の高いワークフローを想定しています。

---

目次

• 概要

• サプライチェーンセキュリティ

• 品質管理・テスト

• 特徴

• インストール

• クイックスタート

• API 例（よく使う関数・メソッド）

• 高度な使い方

  • 部分更新とデフォルト値のマージ
  • マイグレーション
  • SLSA / in-toto provenance の検証

• CI / リリースの説明（簡潔）

• 貢献ガイドライン

• ライセンス

---

概要

ValidKit は、シンプルな辞書スキーマを用いることで、素早く堅牢なバリデーションを行えるよう設計されています。主な対象は設定ファイル（YAML/JSON）、ユーザー入力、外部データの検証です。

設計方針：

• 最小限の依存で高速に動作すること
• 読みやすく直感的なスキーマ記述
• 日本語キーや混在するデータ構造への対応
• CI による自動検証・来歴証明（provenance）との親和性

---

サプライチェーンセキュリティ

本プロジェクトは GitHub Actions および PyPI Trusted Publishing を利用し、すべてのリリースに対して in-toto / SLSA v3 準拠の provenance（来歴証明） を公開しています。

ポイント

• PyPI 側の multiple.intoto.jsonl を含む attestation を生成・保存しています。
• GitHub 側では SLSA provenance（*.intoto.jsonl）を生成し、Release assets に添付しています。
• これにより、配布物が「どのコミット／どの workflow／どの環境」で作られたかを検証できます。

検証例（ローカルで検証する場合）

# slsa-verifier を使った一例（インストール済みであること）
# wheel ファイルと provenance ファイルを用いて検証
slsa-verifier verify-artifact dist/validkit-1.2.3-py3-none-any.whl \
  --provenance multiple.intoto.jsonl \
  --source-uri github.com/disnana/ValidKit

※ 実運用では CI に slsa-verifier を組み込んで自動検証を行うことが推奨されます。

---

品質管理・テスト

本プロジェクトでは、以下を CI にて必須化しています：

• Ruff による lint（自動修正推奨）
• mypy による静的型チェック
• pytest による単体テスト

これらはすべて GitHub Actions に統合され、Pull Request / main ブランチへの push の際に自動実行されます。README 上部の CI バッジから実行状況を確認できます。

---

特徴

• 📝 辞書ベースのスキーマ — クラス定義不要で、設定ファイルの形に合わせてそのままスキーマ化できます。
• 🌏 日本語キー対応 — 日本語のキー名を扱えるため、ローカル向け設定や既存の日本語データとの親和性が高いです。
• 🔗 チェイン可能なバリデータ — v.int().range(1, 10) のように直感的に記述できます。
• 🔄 マイグレーション機能 — 古い形式のデータを検証と同時に変換できます。
• 🛠️ 部分更新・デフォルト値 — 部分的な更新（partial）や base によるデフォルトマージをサポートします。
• 🔍 詳細なエラー収集 — 全エラーを一括で収集し、エラー箇所のパスを分かりやすく表示します。

---

インストール

pip install validkit-py

現時点ではプレリリース版の可能性があります。正式版は PyPI のページで確認してください。

---

クイックスタート

from validkit import v, validate, ValidationError

SCHEMA = {
    "ユーザー名": v.str().regex(r"^\w{3,15}$"),
    "レベル": v.int().range(1, 100),
    "スキル": v.list(v.oneof(["火", "水", "風"])),
    "設定": {
        "通知": v.bool(),
        "言語": v.oneof(["日本語", "English"])
    }
}

data = {
    "ユーザー名": "nana_kit",
    "レベル": 50,
    "スキル": ["火", "風"],
    "設定": {"通知": True, "言語": "日本語"}
}

try:
    validated = validate(data, SCHEMA)
    print("検証成功！", validated)
except ValidationError as e:
    print(f"エラー: {e.path} - {e.message}")

---

API 例（よく使う関数・メソッド）

ここでは代表的な関数・ユースケースを簡潔に示します。実際のシグネチャや追加オプションはドキュメント（/docs）を参照してください。

• v.str(), v.int(), v.bool(), v.list(subschema), v.oneof([...]) — 基本バリデータ

• 連鎖メソッド：.range(min, max), .regex(pattern), .optional(), .default(value) など

• validate(data, schema, *, partial=False, base=None, migrate=None) — 主関数

  • partial=True：不足キーを許容し部分更新を行う
  • base=<dict>：既存のデフォルト値とマージする
  • migrate=<dict|callable>：旧キー→新キーマップや変換関数

• ValidationError — 例外。path / message / errors を持つ

---

高度な使い方

部分更新とデフォルト値のマージ

DEFAULT_CONFIG = {"言語": "English", "音量": 50}
partial_input = {"音量": 80}

updated = validate(
    partial_input,
    SCHEMA,
    partial=True,  # 不足キーを許可
    base=DEFAULT_CONFIG  # デフォルト値とマージ
)

マイグレーション

old_data = {"旧キー": "値", "timeout": 30}

migrated = validate(
    old_data,
    SCHEMA,
    migrate={
        "旧キー": "新キー",
        "timeout": lambda v: f"{v}s"
    }
)

SLSA / in-toto provenance の検証

プロジェクトは自動で provenance を生成しますが、ローカルや企業内のパイプラインで検証するには slsa-verifier 等を利用します。

# 例: wheel と provenance を使った検証
slsa-verifier verify-artifact dist/validkit-1.2.3-py3-none-any.whl \
  --provenance multiple.intoto.jsonl \
  --source-uri github.com/disnana/ValidKit

---

CI / リリースの説明（簡潔）

• ci.yml で以下を実行しています：Lint（Ruff）、Type check（mypy）、Test（pytest）
• main ブランチで新バージョン検出時は自動でビルド・provenance 生成・PyPI 公開・GitHub Release 作成まで行います。
• Publish ジョブは environment: pypi を利用した Trusted Publishing（OIDC）でトークン管理せず安全に署名付きで公開します。

---

貢献ガイドライン

1. Issue を立てる / 相談する
2. Fork → branch を切る
3. テストを追加（該当する場合）
4. PR を作成：変更理由と関連 Issue を記載
5. CI が全て通ること

PR は必ず Lint / mypy / pytest が通ることを条件とします。

---

ライセンス

MIT