کتابخانه Cerberus در پایتون — معرفی و کاربردها

Cerberus یک کتابخانه سبک و منعطف برای اعتبارسنجی داده‌ها در پایتون است. این کتابخانه با تعریف یک schema قابل خواندن به شما اجازه می‌دهد انواع، قوانین و محدودیت‌های داده‌ها را مشخص کنید و ورودی‌ها را به‌سادگی اعتبارسنجی و نرمال‌سازی کنید. Cerberus برای APIها، فرم‌ها، پردازش فایل‌های JSON و هر جایی که نیاز به تضمین ساختار داده وجود دارد مناسب است.

ویژگی‌های کلیدی

• تعریف schema به‌صورت دیکشنری ساده
• پشتیبانی از انواع پایه (string, integer, list, dict, etc.)
• نرمال‌سازی با coerce و default
• قابلیت افزودن اعتبارسنجی‌های سفارشی (custom validators)
• پشتیبانی از nested schema و وابستگی‌ها (dependencies)
• گزینه‌هایی برای allow_unknown، purge_unknown و error reporting

نمونه ساده: تعریف schema و اعتبارسنجی

from cerberus import Validator

schema = {
    'name': {'type': 'string', 'minlength': 1, 'required': True},
    'age': {'type': 'integer', 'min': 0, 'coerce': int},
    'email': {'type': 'string', 'regex': r'^S+@S+.S+$', 'required': True},
    'tags': {'type': 'list', 'schema': {'type': 'string'}, 'default': []}
}

v = Validator(schema)
document = {'name': 'Sara', 'age': '30', 'email': 'sara@example.com'}
if v.validate(document):
    print("Valid:", v.document)
else:
    print("Errors:", v.errors)

این کد یک schema ساده تعریف می‌کند. گزینه coerce برای تبدیل رشته ’30’ به عدد صحیح استفاده شده و اگر اعتبارسنجی موفق باشد، نسخهٔ نرمال‌شدهٔ سند در v.document قرار می‌گیرد. در غیر این صورت، خطاها در v.errors نمایان می‌شوند.

نکات و پارامترهای متداول

نمونه پیشرفته: nested schema و dependencies

schema = {
    'user': {
        'type': 'dict',
        'schema': {
            'id': {'type': 'integer', 'required': True},
            'profile': {
                'type': 'dict',
                'schema': {
                    'bio': {'type': 'string', 'maxlength': 200},
                    'website': {'type': 'string', 'nullable': True}
                }
            }
        }
    },
    'roles': {'type': 'list', 'schema': {'type': 'string'}, 'minlength': 1}
}

v = Validator(schema)
data = {'user': {'id': 10, 'profile': {'bio': 'dev'}}, 'roles': ['admin']}
print(v.validate(data), v.errors)

در این مثال یک سند تو در تو تعریف شده است. Cerberus به‌صورت بازگشتی schema را بررسی می‌کند و خطاها را در ساختار مشابه نشان می‌دهد، که برای دیباگ و نمایش خطاها در API بسیار مفید است.

نوشتن اعتبارسنجی سفارشی (Custom Validator)

from cerberus import Validator

class MyValidator(Validator):
    def _validate_is_even(self, is_even, field, value):
        """ {'type': 'boolean'} """
        if is_even and value % 2 != 0:
            self._error(field, "must be an even number")

schema = {'number': {'type': 'integer', 'is_even': True}}
v = MyValidator(schema)
print(v.validate({'number': 3}), v.errors)

برای اضافه کردن قاعدهٔ جدید، متدهایی با الگوی _validate_ تعریف می‌کنیم. پارامترها شامل مقدار قاعده، نام فیلد و مقدار فیلد هستند. این امکان برای قوانین پیچیده و وابسته به بازرسی‌های بیرونی (مثل دیتابیس) بسیار مفید است.

نرمال‌سازی و تبدیل (Coerce) — مثال بهینه‌سازی

schema = {
    'price': {'type': 'float', 'coerce': float, 'min': 0.0},
    'quantity': {'type': 'integer', 'coerce': int, 'min': 1}
}
v = Validator(schema, purge_unknown=True)
doc = {'price': '12.5', 'quantity': '2', 'extra': 'remove me'}
v.validate(doc)
print(v.document)  # {'price': 12.5, 'quantity': 2}

با استفاده از coerce داده‌ها قبل از اعتبارسنجی تبدیل می‌شوند. گزینه purge_unknown=True باعث حذف فیلدهای نامشخص (در اینجا ‘extra’) می‌شود که در APIها برای جلوگیری از ذخیره‌سازی داده‌های ناخواسته مفید است.

یکپارچه‌سازی با فریم‌ورک‌ها (مثال Flask)

from flask import Flask, request, jsonify
from cerberus import Validator

app = Flask(__name__)
schema = {'username': {'type': 'string', 'required': True}}

@app.route('/users', methods=['POST'])
def create_user():
    v = Validator(schema)
    if not v.validate(request.json):
        return jsonify({'errors': v.errors}), 400
    # استفاده از v.document برای دادهٔ نرمال‌شده
    return jsonify(v.document), 201

در این مثال، قبل از پردازش درخواست، داده‌ها اعتبارسنجی می‌شوند. در صورت خطا، پاسخ با وضعیت 400 و جزئیات خطاها بازگردانده می‌شود. این رویکرد کمک می‌کند منطق اعتبارسنجی از منطق تجاری جدا بماند.

بهترین شیوه‌ها و نکات حرفه‌ای

• برای خطاهای کاربرانه، پیام‌های واضح و محلی‌شده تولید کنید؛ از v.errors استفاده کنید.
• برای داده‌های ورودی از اینترنت همیشه از coerce و purge_unknown استفاده کنید تا داده‌ها امن و پاکیزه بمانند.
• قوانین پیچیده را به custom validatorها واگذار کنید تا schema خواناتر بماند.
• برای مقیاس‌پذیری، schemaها را در ماژول‌های جدا نگهدارید و از ترکیب schemaها استفاده کنید.
• اگر به performance بالاتر یا تایپ‌استاتیک نیاز دارید، Cerberus گزینهٔ سبکی است؛ اما برای مدل‌های پیچیده‌تر ممکن است Pydantic یا Marshmallow مناسب‌تر باشند.

مقایسه کوتاه با کتابخانه‌های دیگر

جمع‌بندی

Cerberus یک ابزار عالی برای اعتبارسنجی و نرمال‌سازی سریع داده‌ها در پروژه‌های پایتون است. با یادگیری الگوهای پایه مثل schemaهای تو در تو، coerce، و نوشتن validatorهای سفارشی می‌توانید کنترل کامل روی ورودی‌ها داشته باشید. برای کاربردهای ساده تا متوسط، Cerberus ترکیبی از سادگی و انعطاف را ارائه می‌دهد.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال