Pythonの強力なデータ検証ライブラリ Cerberus 詳細解説

from cerberus import Validator

# シンプルなスキーマ定義
schema = {
    'name': {'type': 'string'},                    # nameは文字列であるべき
    'age': {'type': 'integer', 'min': 0},         # ageは0以上の整数であるべき
    'city': {'type': 'string', 'required': True}   # cityは必須の文字列であるべき
}

# Validatorのインスタンス化
v = Validator(schema)

# 検証対象のデータ (有効な例)
good_document = {
    'name': 'Alice',
    'age': 30,
    'city': 'Tokyo'
}

# 検証実行
is_valid_good = v.validate(good_document)
print(f"有効なデータの検証結果: {is_valid_good}")  # 出力: 有効なデータの検証結果: True
print(f"エラー内容 (有効なデータ): {v.errors}")   # 出力: エラー内容 (有効なデータ): {}

# 検証対象のデータ (無効な例)
bad_document = {
    'name': 'Bob',
    'age': -5,      # minルール違反
    # 'city' フィールドが欠落 (requiredルール違反)
    'country': 'USA' # スキーマに定義されていないフィールド (デフォルトでは許可される)
}

# 検証実行
is_valid_bad = v.validate(bad_document)
print(f"無効なデータの検証結果: {is_valid_bad}")  # 出力: 無効なデータの検証結果: False
print(f"エラー内容 (無効なデータ): {v.errors}")
# 出力例: エラー内容 (無効なデータ): {'age': ['min value is 0'], 'city': ['required field']}

from cerberus import Validator

schema = {
    'user_id': {'type': 'integer', 'required': True, 'min': 1},
    'username': {'type': 'string', 'required': True, 'minlength': 3, 'maxlength': 20, 'regex': '^[a-zA-Z0-9_]+$'},
    'role': {'type': 'string', 'allowed': ['member', 'admin'], 'default': 'member'},
    'email': {'type': 'string', 'required': False, 'nullable': True, 'regex': '^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$'},
    'is_active': {'type': 'boolean', 'default': True},
    'profile': {
        'type': 'dict',
        'required': False,
        'schema': { # ネストしたスキーマ
            'bio': {'type': 'string', 'maxlength': 200, 'nullable': True},
            'website': {'type': 'string', 'regex': '^https?://.+$', 'nullable': True}
        }
    },
    'tags': {
        'type': 'list',
        'schema': {'type': 'string', 'maxlength': 50} # リスト内の各要素は最大50文字の文字列
    },
    'admin_level': {'type': 'integer', 'required': True, 'dependencies': {'role': 'admin'}} # roleが'admin'の時だけ必須
}

v = Validator(schema)

valid_data = {
    'user_id': 101,
    'username': 'test_user',
    'role': 'admin', # roleがadminなのでadmin_levelが必須になる
    'email': None,
    'profile': {'bio': 'Hello!', 'website': 'https://example.com'},
    'tags': ['python', 'validation'],
    'admin_level': 5 # dependenciesを満たす
}

invalid_data = {
    'user_id': 0, # min違反
    'username': 'test user', # regex違反 (スペースが含まれる)
    # 'role' が欠落 (allowedのデフォルト 'member' が適用されるが、admin_levelがないため問題ない)
    'is_active': 'yes', # boolean違反
    'profile': {'website': 'invalid-url'}, # regex違反
    'tags': ['long_tag_that_exceeds_fifty_characters_limit_aaaaaaaaaaaa'], # maxlength違反
    'role': 'admin', # roleがadmin
    # admin_level が欠落 (dependencies違反)
}

print("--- Valid Data ---")
print(f"Validation result: {v.validate(valid_data)}")
print(f"Errors: {v.errors}")
print(f"Normalized data: {v.normalized(valid_data)}") # default値が適用されたデータ

print("\n--- Invalid Data ---")
print(f"Validation result: {v.validate(invalid_data)}")
print(f"Errors: {v.errors}")

from cerberus import Validator
import datetime

def to_uppercase(value):
    if isinstance(value, str):
        return value.upper()
    return value

def parse_date(value):
    try:
        # YYYY-MM-DD形式を期待
        return datetime.datetime.strptime(value, '%Y-%m-%d').date()
    except (ValueError, TypeError):
        return value # パースできない場合は元の値を返す (後続のtype検証でエラーになる)

schema = {
    'item_code': {'type': 'string', 'coerce': to_uppercase, 'required': True},
    'quantity': {'type': 'integer', 'coerce': int, 'min': 1}, # 文字列で来ても整数に変換
    'price': {'type': 'float', 'coerce': float},
    'category': {'type': 'string', 'default': 'uncategorized'},
    'purchase_date': {'type': 'date', 'coerce': parse_date, 'nullable': True}
}

# rename/purge_unknown は Validator インスタンスで設定
# v = Validator(schema, purge_unknown=True)

# または rename_handler を使う
# def custom_rename(field):
#     if field == 'old_name':
#         return 'new_name'
#     return field
# v = Validator(schema, rename_handler=custom_rename)


v = Validator(schema)

data = {
    'item_code': 'abc-123',
    'quantity': '10', # 文字列だがcoerceでintに変換される
    'price': '99.99',
    'extra_field': 'this will be kept by default',
    'purchase_date': '2025-04-01'
}

if v.validate(data):
    print("Validation successful!")
    normalized_data = v.normalized(data)
    print("Normalized data:")
    print(normalized_data)
    # 出力例:
    # Normalized data:
    # {'item_code': 'ABC-123', 'quantity': 10, 'price': 99.99, 'category': 'uncategorized', 'extra_field': 'this will be kept by default', 'purchase_date': datetime.date(2025, 4, 1)}
else:
    print(f"Validation failed: {v.errors}")

# categoryがなくてもdefaultで補完される例
data_no_category = {
    'item_code': 'xyz-789',
    'quantity': 5,
    'price': 150.00
}
if v.validate(data_no_category):
     print("\nValidation successful (no category)!")
     print(f"Normalized data: {v.normalized(data_no_category)}")
     # 出力例: Normalized data: {'item_code': 'XYZ-789', 'quantity': 5, 'price': 150.0, 'category': 'uncategorized'}

from cerberus import Validator

complex_schema = {
    'user': {
        'type': 'dict',
        'required': True,
        'schema': { # ネストした辞書のスキーマ
            'id': {'type': 'integer', 'required': True},
            'name': {'type': 'string', 'required': True}
        }
    },
    'permissions': {
        'type': 'list',
        'required': False,
        'schema': {'type': 'string', 'allowed': ['read', 'write', 'admin']} # リスト要素のスキーマ
    },
    'settings': {
        'type': 'dict',
        'valueschema': {'type': 'boolean'} # 全てのsetting値はbooleanであるべき
    },
    'dynamic_fields': {
        'type': 'dict',
        'propertyschema': { # キーが 'prop_' で始まるフィールド
            'startsWith_prop_.*': {'type': 'string', 'maxlength': 10}
        },
        'valueschema': {'type': 'integer'} # それ以外のフィールドの値は整数
    }
}

v = Validator(complex_schema)

data = {
    'user': {'id': 1, 'name': 'Charlie'},
    'permissions': ['read', 'write'],
    'settings': {
        'enable_notifications': True,
        'dark_mode': False
    },
    'dynamic_fields': {
        'startsWith_prop_A': 'valueA', # propertyschemaにマッチ
        'startsWith_prop_B': 'valueB', # propertyschemaにマッチ
        'other_field': 123 # valueschemaにマッチ
    }
}

invalid_data_example = {
    'user': {'id': 'not-an-int'}, # 型エラー
    'permissions': ['read', 'execute'], # allowed違反
    'settings': {'feature_x': 'enabled'}, # valueschema違反 (booleanでない)
    'dynamic_fields': {
        'startsWith_prop_C': 'this string is too long', # propertyschemaのmaxlength違反
        'another_field': 'not-an-int' # valueschema違反
    }
}

print("--- Complex Valid Data ---")
print(f"Validation result: {v.validate(data)}")
print(f"Errors: {v.errors}")

print("\n--- Complex Invalid Data ---")
print(f"Validation result: {v.validate(invalid_data_example)}")
print(f"Errors: {v.errors}")

from cerberus import Validator

schema = {
    'known_field': {'type': 'string'}
}

# 1. デフォルト (未知のフィールドを許可)
v_allow = Validator(schema)
data = {'known_field': 'hello', 'unknown_field': 123}
print(f"Default allow_unknown: {v_allow.validate(data)}, Errors: {v_allow.errors}") # True, {}

# 2. 未知のフィールドを禁止
v_disallow = Validator(schema, allow_unknown=False)
print(f"allow_unknown=False: {v_disallow.validate(data)}, Errors: {v_disallow.errors}") # False, {'unknown_field': ['unknown field']}

# 3. 未知のフィールドを許可し、値を検証
v_validate_unknown = Validator(schema, allow_unknown={'type': 'integer'})
data_valid_unknown = {'known_field': 'world', 'another_unknown': 456}
data_invalid_unknown = {'known_field': 'world', 'invalid_unknown': 'abc'}
print(f"allow_unknown=schema (valid): {v_validate_unknown.validate(data_valid_unknown)}, Errors: {v_validate_unknown.errors}") # True, {}
print(f"allow_unknown=schema (invalid): {v_validate_unknown.validate(data_invalid_unknown)}, Errors: {v_validate_unknown.errors}") # False, {'invalid_unknown': ['must be of integer type']}

# 4. purge_unknown=True で未知のフィールドを除去
v_purge = Validator(schema, allow_unknown=True, purge_unknown=True) # allow_unknown=Trueがないとpurgeされない
if v_purge.validate(data):
    print(f"purge_unknown=True: Normalized: {v_purge.normalized(data)}") # {'known_field': 'hello'}

from cerberus import Validator

class MyValidator(Validator):
    def _validate_is_odd(self, constraint, field, value):
        """ constraint が True の場合、値が奇数であることを検証します。
        The rule's arguments are validated against this schema:
        {'type': 'boolean'}
        """
        if constraint is True and not isinstance(value, int):
             # 事前に型チェックが必要な場合がある
             # この例では type: integer がスキーマにある前提
             pass
        elif constraint is True and isinstance(value, int) and not bool(value & 1):
            # self._error(フィールド名, エラーメッセージ)
            self._error(field, "Must be an odd number")

    def _validate_divisible_by(self, divisor, field, value):
        """ 値が指定された除数で割り切れることを検証します。
        The rule's arguments are validated against this schema:
        {'type': 'integer', 'min': 1}
        """
        if not isinstance(value, int):
            pass # 型エラーは 'type' ルールに任せる
        elif value % divisor != 0:
            self._error(field, f"Must be divisible by {divisor}")

# カスタムルールを使ったスキーマ
schema = {
    'odd_number': {'type': 'integer', 'is_odd': True}, # _validate_is_odd が呼ばれる
    'multiple_of_5': {'type': 'integer', 'divisible_by': 5} # _validate_divisible_by が呼ばれる
}

v = MyValidator(schema) # カスタムValidatorを使用

data1 = {'odd_number': 9, 'multiple_of_5': 10}
print(f"Data1 valid: {v.validate(data1)}, Errors: {v.errors}") # True, {}

data2 = {'odd_number': 8, 'multiple_of_5': 12}
print(f"Data2 valid: {v.validate(data2)}, Errors: {v.errors}")
# False, {'odd_number': ['Must be an odd number'], 'multiple_of_5': ['Must be divisible by 5']}

# ルール引数の検証 (docstring内のスキーマに基づく)
invalid_schema = {'multiple_of_5': {'divisible_by': 0}} # divisor は 1以上である必要がある
try:
    MyValidator(invalid_schema)
except Exception as e:
    print(f"\nInvalid schema error: {e}")

from cerberus import Validator, errors

def check_is_palindrome(field, value, error):
    """ 値が回文かどうかをチェックする """
    if isinstance(value, str) and value != value[::-1]:
        # error(フィールド名, エラーメッセージ) を呼び出す
        error(field, "Must be a palindrome")

schema_func = {
    'word': {'type': 'string', 'check_with': check_is_palindrome}
}

# MyValidatorクラス (前の例から) のメソッドを参照することも可能
schema_class_ref = {
     'another_odd': {'type': 'integer', 'check_with': 'is_odd', 'is_odd': True}
}


v_func = Validator(schema_func)
v_class_ref = MyValidator(schema_class_ref) # カスタムValidatorが必要

print(f"Palindrome check ('level'): {v_func.validate({'word': 'level'})}, Errors: {v_func.errors}") # True, {}
print(f"Palindrome check ('hello'): {v_func.validate({'word': 'hello'})}, Errors: {v_func.errors}") # False, {'word': ['Must be a palindrome']}

print(f"Odd check (class ref, 7): {v_class_ref.validate({'another_odd': 7})}, Errors: {v_class_ref.errors}") # True, {}
print(f"Odd check (class ref, 6): {v_class_ref.validate({'another_odd': 6})}, Errors: {v_class_ref.errors}") # False, {'another_odd': ['Must be an odd number']}

from cerberus import Validator
import re
from decimal import Decimal, InvalidOperation

class RichValidator(MyValidator): # 前の例のMyValidatorを継承
    def _validate_type_email(self, field, value):
        """ 簡単なメールアドレス形式を検証するカスタム型 """
        if not isinstance(value, str) or not re.match(r"[^@]+@[^@]+\.[^@]+", value):
            self._error(field, "Must be a valid email address (custom type)")

    def _validate_type_decimal(self, field, value):
        """ decimal.Decimal 型を検証するカスタム型 """
        try:
            # 文字列からの変換も試みる（必要に応じて）
            if isinstance(value, str):
                 Decimal(value)
            elif not isinstance(value, Decimal):
                 raise TypeError
        except (InvalidOperation, TypeError):
            self._error(field, "Must be a valid Decimal")


schema_custom_type = {
    'contact_email': {'type': 'email', 'required': True}, # カスタム型 'email'
    'precise_value': {'type': 'decimal', 'required': True} # カスタム型 'decimal'
}

v_rich = RichValidator(schema_custom_type)

data_ok = {'contact_email': 'test@example.com', 'precise_value': Decimal('123.456')}
print(f"\nCustom type (valid): {v_rich.validate(data_ok)}, Errors: {v_rich.errors}") # True, {}

data_ng = {'contact_email': 'invalid-email', 'precise_value': 12.34 } # floatはDecimalではない
print(f"Custom type (invalid): {v_rich.validate(data_ng)}, Errors: {v_rich.errors}")
# False, {'contact_email': ['Must be a valid email address (custom type)'], 'precise_value': ['Must be a valid Decimal']}