العودة إلى كل المقالات
برمجة وتطوير آخر تحديث: 31 أكتوبر 2026

لماذا تختفي False و0 من إعدادات مشروع الصور؟ أصلح الدمج قبل إرسال الطلب

صندوق تحكم معدني بثلاثة مقابض ومفتاح بجوار حاسوب ودفتر مفتوح وقلم على مكتب قرب نافذة
صندوق تحكم معدني بثلاثة مقابض ومفتاح بجوار حاسوب ودفتر مفتوح وقلم على مكتب قرب نافذة.

أعادت broken_merge القيم watermark=True وseed=7 وstrength=0.8 رغم أن رقعة الاختبار طلبت False و0 و0. مصدر الفرق هو patch.get(key) or value، لا تخزين الملفات أو اختيار مزود صور. يدرس هذا المثال أربع حقول محلية اختيرت لشرح بناء إعدادات مشروع؛ لم تُرسل إلى خدمة توليد ولا تقيس أثر البذرة أو القوة أو العلامة المائية على أي صورة. سيصلح merge_settings طريقة تطبيق القيم، ثم يحدد validate ما يقبله العقد من أنواع وحدود. وفي الامتداد الأخير سنضيف عملية صريحة لاستعادة افتراضي حقل معين، حتى لا يستعمل التطبيق الصفر أو None إشارة مبهمة لعمليتين مختلفتين.

ابدأ بثلاث قيم طلبتها ثم فقدها الدمج

في المثال البرمجي المعتمد، يمتلك قاموس الأساس أربع قيم محددة: prompt بالنص ceramic cup، وwatermark بالقيمة المنطقية True، وseed بالقيمة العددية 7، وstrength بالقيمة 0.8. عندما نرسل قاموس تعديل يحتوي على watermark=False وseed=0 وstrength=0، تعيد الدالة المعيبة broken_merge القاموس بالقيم الأصلية True و7 و0.8 متجاهلة كل ما ورد في التعديل. بالمقابل، تعيد الدالة المصححة merge_settings النتيجة الدقيقة المطلوبة: watermark=False وseed=0 وstrength=0 مع بقاء prompt مساوياً لنص ceramic cup الأصلي. هذا التباين الحسابي الصريح بين الدالتين يكشف كيف تتحول القيم العددية والمنطقية الصالحة إلى ضحايا لاختزال منطقي زائف يفرض الافتراضيات قسراً على المستخدم.

يعود سبب هذا الإخفاق في دالة broken_merge إلى استخدام التعبير القائم على استدعاء patch.get(key) or value داخل بناء القاموس الجديد. عندما تبحث الدالة عن المفتاح watermark داخل رقعة التعديل، تعيد الدالة القيمة المنطقية False. وحيث إن False تُقيّم في بايثون كقيمة غير متحققة، ينتقل معامل or فوراً إلى الشق الأيمن ويعيد القيمة الأصلية True من قاموس الأساس. ويتكرر الموقف نفسه حرفياً مع seed=0 وstrength=0، حيث يُقيّم الصفر العددي كقيمة خادعة في المنطق البولياني، مما يجبر معامل or على اختيار الرقم 7 ومعامل القوة 0.8. وبذلك تُعامل كل مدخلة مساوية للصفر أو False كأنها غير مرسلة على الإطلاق.

تطبق merge_settings رقعة التعديل على نسخة جديدة من قاموس الأساس: تنشئ merged = dict(base)، ثم تستعمل merged.update(patch). تمر القيم المرسلة دون تقييم صدقها المنطقي، وبعدها يفحص validate القاموس الناتج. لا تصبح أي قيمة مقبولة لمجرد أن update استطاعت وضعها في القاموس؛ فمثلاً seed=None يمر إلى النسخة ثم يرفضه فحص النوع. هذا هو الفرق بين اختيار القيمة والتحقق منها. أما الحقول الغائبة من الرقعة فتبقى على قيم الأساس، دون حاجة لإعادة إرسالها كلها. تستطيع قراءة هذا الترتيب في المصدر قبل تعديل التطبيق، وتستطيع الاحتفاظ بالاختبار الذي يجمع False و0 و0 كحالة انحدار تكشف عودة استخدام or في الدمج.

افصل غياب المفتاح عن False والصفر وNone

يتطلب الفهم الدقيق لدمج الإعدادات التمييز الرياضي والبرمجي بين ثلاث حالات متباينة جذرياً: غياب المفتاح تماماً كما في القاموس الفارغ {}، ووجود المفتاح مقترناً بالصفر العددي كما في {'seed': 0}، ووجود المفتاح مقترناً بالقيمة الخالية كما في {'seed': None}. في الحالة الأولى، يعني الغياب رغبة المستخدم في إبقاء القيمة الافتراضية 7 المستمدة من الأساس. وفي الحالة الثانية، يعبر الصفر عن اختيار صريح لبذرة تبدأ من الصفر، وهي قيمة مقبولة كلياً في المخطط المحلي. أما في الحالة الثالثة، فإن تمرير None يمثل قيمة غير صالحة لحقل البذرة الذي يشترط عدداً صحيحاً، وبالتالي يجب أن يرفضها التحقق استناداً إلى بطلان نوعها وليس لكونها غير مرسلة.

يُعد False والصفر وNone والحاويات الفارغة قيماً خاطئة منطقياً في Python، ويعيد or أحد معامليه. لا يختبر هذا العامل وجود المفتاح في قاموس إعدادات. Python3.12 truth testing and dict.update

ينشأ الخلط عند المطورين بسبب طبيعة عمل معامل or في بايثون؛ فهذا المعامل لا يختبر عضوية المفاتيح داخل القواميس ولا يكافئ التحقق بأسلوب in. يكتفي معامل or بإعادة المعامل الأول إذا كان تقييمه المنطقي صواباً، ويعيد الثاني إذا كان الأول غير متحقّق. ولذلك، فإن استخدام patch.get(key) or value يُعد خطأً تصميمياً صريحاً، لأن get تعيد القيمة الحقيقية المخزنة للمفتاح، فإذا كانت False أو 0 سقطت في اختبار الصدق المنطقي وانحرفت النتيجة نحو الأساس. اختبار الحضور الحقيقي يتطلب فحص وجود المفتاح في patch عبر in أو استخدام تحديث القواميس التراكمي الذي يتجاهل تماماً الصدق المنطقي للقيم المدمجة.

بعد تحديد قيم الإعدادات يمكن تثبيت هوية طلب الصور وفق عقد واضح. لا تحسب مفتاح الطلب قبل أن تعرف هل الصفر اختيار فعلي أم قيمة استبدلها الدمج؛ مقال الهوية يعالج مرحلة أخرى ولا يغني عن تحقق الإعدادات.

تظهر مغالطة شائعة أخرى في التعامل مع القيم الخاصة مثل float('nan') بالمقارنة مع None وFalse و0. في لغة بايثون، يُقيّم float('nan') منطقياً على أنه صواب، حيث يعيد تعبير bool(float('nan')) النتيجة True دائماً، بخلاف None والصفر وFalse التي تُقيّم كقيم خادعة. هذا يعني أن الدالة المعيبة broken_merge لو استقبلت strength=float('nan') لكانت احتفظت به ولم تستبدله بـ 0.8، مع كونه قيمة رياضية غير محددة تكسر العمليات الحسابية اللاحقة. إن دالة validate المحلية ترفض float('nan') صراحة عبر شرط math.isfinite وليس بسبب تقييمه البولياني، مما يؤكد ضرورة بناء الفحص على الأنظمة والخواص الرياضية المحددة.

تفحص merge_settings نوع الأساس والرقعة ثم صحة الأساس، وترفض مفاتيح الرقعة غير المعروفة قبل إنشاء القاموس الجديد. تأتي النسخة عبر dict(base)، ويليها update ثم فحص merged. هذه نسخة سطحية لقاموس مسطح، لا نسخة مستقلة من كل كائن متداخل محتمل. يوضح الفصل بين الخطوات أين يظهر الرفض: غياب مفتاح مطلوب من الأساس يختلف عن ظهور مفتاح غريب في الرقعة، وكلاهما يختلف عن وجود قيمة غير مقبولة في النتيجة. لا تتجاهل الاستثناء ثم ترسل إعدادات الأساس تلقائياً، لأن ذلك قد يخفي اختياراً رفضه العقد. طريقة معالجة الرفض في واجهة المشروع قرار آخر لم تنفذه هذه الدالة.

settings_merge.py

import math

FIELDS = {'prompt', 'watermark', 'seed', 'strength'}

def broken_merge(base, patch):
    return {key: patch.get(key) or value for key, value in base.items()}

def validate(config):
    if set(config) != FIELDS:
        raise ValueError('Expected the complete four-field local schema')
    if not isinstance(config['prompt'], str) or not config['prompt'].strip():
        raise ValueError('A nonblank prompt is required')
    if type(config['watermark']) is not bool:
        raise ValueError('watermark must be boolean')
    if type(config['seed']) is not int or config['seed'] < 0:
        raise ValueError('seed must be a nonnegative integer')
    value = config['strength']
    if type(value) not in (int, float) or not math.isfinite(value) or not 0 <= value <= 1:
        raise ValueError('strength must be finite and within zero to one')

def merge_settings(base, patch):
    if not isinstance(base, dict) or not isinstance(patch, dict):
        raise TypeError('Expected dictionaries')
    validate(base)
    if set(patch) - FIELDS:
        raise ValueError('Unknown override field')
    merged = dict(base)
    merged.update(patch)
    validate(merged)
    return merged

نطاق التحقق المحلي: Eleven unittest methods on a flat local four-field schema. These are invented project fields, not options claimed for an actual image provider. No image generation, parameter efficacy or seed reproducibility experiment, no nested merge, file saving, environment precedence, API validation, version migration or concurrency tested. False and zero are valid in this local contract; empty prompt and None are rejected. Flat primitive schema permits shallow dict copying; not a general deep-copy guarantee.؛ البيئة: Python3.12.3 on Windows

حدد حقول المشروع الأربعة وحدودها المحلية

يحدد العقد المحلي في ملف settings_merge.py أربعة حقول مغلقة ومصمتة لا تقبل الزيادة أو النقصان، وهي: prompt وwatermark وseed وstrength، مجمعة داخل المتغير الثابت FIELDS. هذا المخطط محلي بحت ومصمم لاختبار قواعد الدمج الأساسية، ولا يدعي التوافق مع أي واجهة برمجية تجارية لتوليد الصور أو منصة خارجية لخدمات الذكاء الاصطناعي. ترفض دالة validate أي قاموس ينقصه أحد هذه الحقول الأربعة أو يحتوي على حقل إضافي خامس عبر المقارنة المباشرة set(config) != FIELDS، مما يضمن أن الهيكل الإجمالي للمشروع يظل مسطحاً ومحصوراً في الحدود المقررة سلفاً.

يخضع حقل prompt لاختبارين متتابعين: الأول هو التحقق من النوع عبر isinstance(config['prompt'], str)، والثاني هو التأكد من احتوائه على محتوى نصي فعلي عبر شرط not config['prompt'].strip(). إذا كان النص فارغاً تماماً أو يتألف من مسافات بيضاء فقط مثل ' '، ترفع الدالة استثناء ValueError يفيد باشتراط نص غير فارغ. والجدير بالملاحظة أن هذا التحقق يكتفي بفحص النص ولا يجري تعديلاً أو إزالة للمسافات من السلسلة المعادة، بل يُعاد القاموس محتفظاً بالسلسلة النصية كما هي طالما أنها احتوت على محارف غير بيضاء.

يشترط حقل watermark أن تكون القيمة المنطقية صريحة من خلال التحقق الصارم type(config['watermark']) is not bool. تم استخدام فحص النوع المباشر بدلاً من isinstance لتفادي الخلط، حيث تُرفض الأرقام الصحيحة مثل 1 و0 وكذلك السلاسل النصية مثل 'true' أو 'false'. هذا الشرط يضمن أن المستخدم الذي يرغب في إيقاف العلامة المائية يرسل القيمة المنطقية False تحديداً، وأن النظام يقبل هذه القيمة ويرفض أي تمثيل رمزي غير بولياني قد يتسلل من طبقات إدخال غير منضبطة.

يفرض حقل seed قيدين متلازمين: الأول أن يكون النوع عدداً صحيحاً عبر type(config['seed']) is not int، والثاني ألا يكون سالباً عبر config['seed'] < 0. يُعد فحص النوع الدقيق type حاسماً هنا لأن فئة bool في بايثون ترث من فئة int، وبالتالي فإن التعبير isinstance(False, int) يعيد True؛ ولو استخدمنا isinstance لقبلت الدالة تمرير False كبذرة عددية. كما يسمح شرط عدم السلبية بقبول الصفر 0 كأول عدد صحيح موجب أو صفري، في حين يتم رفض الأعداد السالبة مثل -1 برفع استثناء صريح.

يخضع حقل strength لقيود عددية ورياضية دقيقة؛ إذ يشترط التحقق أن يكون النوع من ضمن الفئات العددية type(value) in (int, float)، وأن يكون الرقم منتهياً ومحدداً عبر math.isfinite(value)، بالإضافة إلى وقوعه حصرياً ضمن النطاق المغلق بين الصفر والواحد عبر 0 <= value <= 1. يستبعد شرط math.isfinite القيم غير المعرفة مثل float('nan') والقيم اللانهائية float('inf') وfloat('-inf'). كما يتيح فحص النطاق قبول الحواف بدقة متناهية، فالقيمة 0 والقيمة 1 مقبولتتان تماماً، بينما يتم استبعاد القيم المتطرفة مثل -0.1 أو 1.1 فوراً برفع ValueError.

اقرأ الدمج والتحقق بالترتيب الفعلي

تبدأ الدالة بشرط isinstance للمعاملين base وpatch وترفع TypeError إذا لم يكونا قاموسين. يمرر اختبار test_string_input نصاً مكان الرقعة ويتوقع هذه الفئة من الاستثناء. هذا التحقق يحدد مدخل الدالة، لكنه ليس فحصاً لأمان كل كائن يمكن تمريره من مصدر خارجي. ثم تُطبق قواعد الحقول على القواميس المقبولة. احتفظ بالفرق عند كتابة رسائل الواجهة: قد تكون المشكلة أن التمثيل الوارد ليس قاموساً أصلاً، أو أنه قاموس بقيمة حقل مرفوضة. لا تجمع الحالتين تحت ادعاء أن دالة الدمج تصلح الإدخال تلقائياً؛ فهي ترفضه وترجع التحكم إلى المستدعي بدلاً من تخمين ما قصده.

في الخطوة الثانية، تخضع إعدادات الأساس لفحص شامل باستدعاء validate(base) قبل الشروع في دمج أي رقعة. هذا الفحص المسبق يعني أنه لو كان قاموس الأساس فاسداً بالأصل، مثل احتوائه على seed=-1، فإن الدالة سترفض العملية وتطلق استثناء ValueError فوراً. لا يمكن لرقعة تعديل سليمة تحتوي على seed=0 أن تعالج أو تتستر على أساس معطوب مسبقاً، وقد أثبت اختبار الوحدة المخصص test_bad_base_rejected_even_if_patch_could_fix هذا السلوك الحتمي برفض العملية رغم صلاحية التعديل المقترح.

قبل النسخ والتحديث، تحسب الدالة set(patch) – FIELDS. وجود extra في الرقعة يجعل هذه المجموعة غير فارغة، فيُرفع ValueError قبل تطبيق أي قيمة. هذه سياسة لرفض الحقول غير المعروفة، بدلاً من تجاهلها بصمت أو توسيع المخطط تلقائياً. يفحص test_unknown_field الحالة dict(extra=1). لا يثبت ذلك سلوك كل مهايئ لنموذج ويب أو كل طريقة لترميز البيانات؛ إنه تأكيد على هذا القاموس المحدد. إن أردت لاحقاً السماح ببيانات وصفية، فاختر لها موضعاً خارج الرقعة أو وسّع العقد واختباره. لا تعتمد على نجاح update وحدها لتقرر أن مفتاحاً جديداً له معنى في المشروع.

بعد اجتياز الخطوات السابقة، تنشئ الدالة نسخة جديدة عبر merged = dict(base) ثم تطبق التعديل المباشر merged.update(patch). وفي الخطوة السادسة وقبل إعادة الكائن، تستدعي الدالة validate(merged) للتحقق من المزيج النهائي بالكامل. يضمن هذا الفحص البعدي أن القيم المستحدثة لا تكسر الشروط العامة، مثل تعديل النص إلى فراغات أو إرسال رقم خارج المجال. بمجرد اجتياز هذا التدقيق بنجاح، تعيد الدالة القاموس المدمج للمستدعي، محققة التكامل التام بين الإعدادات الأساسية والتعديلات الصريحة.

اختبر اختيارات المستخدم لا مجرد شكل القاموس

تخضع دالة الدمج لحزمة اختبارات وحدة محلية تتألف من إحدى عشرة طريقة اختبار منفصلة تنفذ بواسطة وحدة unittest القياسية في بايثون دون الاعتماد على مكاتب خارجية. لا تكتفي هذه الاختبارات بفحص الشكل الخارجي للقاموس أو التأكد من عدد المفاتيح، بل تمتد لتختبر مصير القرارات الصريحة التي يتخذها المستخدم. تبدأ الاختبارات بطريقة test_reproduce_false_and_zero_loss التي تعيد محاكاة الفقدان الحسابي في دالة broken_merge وتؤكد إعادتها للقيم القديمة True و7 و0.8، لتقابلها طريقة test_preserve_false_and_zero التي تثبت حفظ merge_settings للقيم False و0 و0.

تغطي الاختبارات التالية حالات التفاعل مع الأنواع والحدود المرفوضة؛ فطريقة test_missing_keeps_base تتأكد من أن تمرير قاموس تعديل فارغ يبقي seed مساوياً لـ 7 المستمدة من الأساس، في حين تضمن test_unknown_field رفض الحقول الغريبة عبر تمرير dict(extra=1). وتثبت طريقة test_none_is_not_missing أن تمرير seed=None ليس معادلاً لغياب المفتاح بل يرفع ValueError، وتؤكد test_bool_is_not_seed رفض تمرير seed=False. وفي حقل القوة، تفحص طريقة test_nonfinite_strength عبر اختبارات فرعية subTest كلاً من float('nan') وfloat('inf') و-0.1 و1.1 وتتحقق من رفضها جميعاً داخل طريقة اختبار واحدة.

تختبر طريقة test_blank_prompt رفض النصوص المكونة من فراغات عبر dict(prompt=' ')، في حين تتحقق test_string_input من رفع TypeError إذا تم تمرير سلسلة نصية بدلاً من القاموس. أما طريقة test_input_dicts_unchanged، فتفحص سلامة القواميس المدخلة بالتأكد من أن استدعاء merge_settings مع patch=dict(seed=0) لا يغير قاموس base ولا رقعة patch نهائياً مقارنة بنسخة مستقلة أخذت مسبقاً عبر copy.deepcopy. يجب التأكيد على أن هذه الحزمة تختبر عقداً مسطحاً بقيم أولية معزولة داخل بيئة بايثون 3.12 المحلية، ولا تمثل فحصاً لواجهات مستخدم أو استدعاءات شبكية أو توليداً فعلياً للصور.

افصل النسخة المسطحة عن إعدادات متداخلة

تحدّث dict.update مفاتيح القاموس من البيانات المعطاة، لذلك يستعمل المثال نسخة من الأساس ثم يطبّق حقول التعديل الصريحة قبل فحص النتيجة. Python3.12 truth testing and dict.update

يقوم العقد الحالي على مخطط مسطح يتألف من أربعة حقول ذات قيم أولية غير قابلة للتغيير في مواضعها: نصوص، وقيم منطقية، وأعداد صحيحة وعشرية. في مثل هذه الهيكلية البسيطة، يُعد النسخ السطحي عبر dict(base) كافياً وفعالاً تماماً، حيث يتم استنساخ أزواج المفاتيح والقيم دون خوف من مشاركة مراجع لكائنات قابلة للتعديل مثل القوائم أو القواميس الفرعية. يؤكد الاختبار test_input_dicts_unchanged ثبات القاموسين الأصليين بعد الدمج، لكن هذا الثبات يرتكز على بساطة الأنواع المعتمدة ولا يشكل ضمانة عامة لعمليات النسخ العميق عبر كافة الهياكل المعقدة.

إذا جاءت رقعة بمفتاح render وقاموس داخلي، فسترفض merge_settings المفتاح render في فحص المفاتيح غير المعروفة قبل الوصول إلى update، لأن FIELDS لا يحتويه. هذا سلوك متوقع من عقد مسطح، وليس تنفيذاً ناقصاً لدمج تعاودي. وإذا قررت إدخال بنية متداخلة في إصدار جديد، فسيتطلب ذلك تعريف قاعدة تحقق جديدة أولاً. بعدها اختر هل يستبدل الكائن كله أم تدمج حقوله، وما الذي يعنيه إرسال قائمة فارغة أو قيمة None. لا يكفي تغيير مجموعة FIELDS وترك بقية الدوال كما هي؛ فملكية الكائنات المتداخلة وطريقة نسخها ستحتاجان قراراً واختبارات لم تجر في التجربة الحالية.

عند توسيع المشاريع لدعم التكوينات المتداخلة، تبرز خيارات تصميمية متباينة تستوجب الحسم الصريح: إما استبدال الكائن المتداخل بالكامل عند وروده في رقعة التعديل، أو إجراء دمج تعاودي عميق يدمج الحقول الفرعية طبقة تلو الأخرى. كما تتطلب إدارة القوائم المتداخلة قراراً مماثلاً حول ما إذا كان التعديل يستبدل القائمة برمتها أم يلحق عناصر جديدة بها. وإذا تقرر في المستقبل السماح بالقيمة None كقيمة صالحة تعني إلغاء التعيين الصريح، فسيتحتم استخدام كائنات حارسة مستقلة sentinel للتمييز بين عدم إرسال المفتاح وتمريره بقيمة تفريغ متعمدة.

الدمج التعاودي ونسخ الكائنات المتداخلة وتخصيص sentinel بدائل مقترحة، ولا توجد لها نتائج تنفيذ في هذه المجموعة. اختر أحدها فقط عندما يكون لديك احتياج محدد يستطيع الاختبار التعبير عنه. لا يوجد قياس هنا لسرعة هذه البدائل أو استهلاكها للذاكرة، ولا سبب لاعتبارها أكثر موثوقية لمجرد كثرة طبقاتها. حافظ أولاً على حالة False والصفر التي أصلحها العقد المسطح، ثم أضف حالات جديدة تصف ما يتغير. أما امتداد الاستعادة أدناه فسيبقى مسطحاً ويعيد استخدام validate نفسها، لذلك لا يقدم طريقة غير معلنة لتمرير نوع متداخل أو تجاوز فحص الحقول.

اربط الطبقات بواجهة مشروع دون ادعاء توافق مزود

قد تسلم واجهة مقترحة قيمة عددية كنص "0"، أو تميز بين حقل لم يرسل واختيار صريح False. يجب أن يحدد مهايئ الواجهة هذا الفرق قبل استدعاء الدالة؛ لم تُبن هنا استمارة أو طريقة إرسال خاصة بها. تمرير seed="0" مباشرة إلى merge_settings يفشل في validate برفع ValueError وفق الشيفرة، لا TypeError؛ فالمعامل نفسه قاموس صحيح لكن قيمة الحقل تخالف شرط int. في المقابل يخص TypeError تمرير مدخل ليس قاموساً في فحص بداية الدالة. لا تستنتج سبب الاستثناء من قيمة افتراضية عادت في الشاشة: افحص الحمولة التي اختار المهايئ تكوينها، ثم ضع اختباراً لذلك المهايئ إذا قررت تنفيذه.

يتطلب هذا التباين بناء طبقة مهايئ وسيطة تتولى تفكيك مدخلات الواجهة وتحويلها إلى الأنواع المتوافقة مع المخطط المحلي قبل تمريرها لدالة الدمج. ويجب أن يلتزم هذا المهايئ بقواعد تحويل واضحة ومستقلة؛ فلا يجوز استخدام التحويل التلقائي bool('false') في بايثون لأنه يعيد True بصورة مضللة نظراً لكون السلسلة غير فارغة. يتعين على المهايئ فحص السلاسل النصية صراحة، وتحويل '0' إلى العدد 0، والتمييز بين الغياب التام للمدخل الذي يترجم إلى استبعاد المفتاح من رقعة التعديل، وتمرير القيم الصريحة المطابقة للأنواع المطلوبة.

تقتضي الممارسة البرمجية المنضبطة ترجمة الأخطاء التقنية المرتفعة من دالة التحقق، مثل ValueError وTypeError، إلى رسائل واضحة ومفهومة لمستخدم الواجهة. إلا أن هذه الطبقة من ترجمة الأخطاء وربطها بحقول النموذج تظل تصميماً مقترحاً ومسؤولية تقع على عاتق الواجهة المستدعية، ولم يتم تنفيذها أو تضمينها داخل كود settings_merge.py. يكتفي الكود الحالي برفع الاستثناءات القياسية لبايثون عند رصد أي مخالفة للمخطط، تاركاً لمنطق التطبيق الأعلى تحديد كيفية معالجتها وعرضها للمستخدم النهائي.

بعد اكتمال الدمج والتحقق بنجاح واستخراج القاموس النهائي المعتمد، يمكن لمكونات النظام اللاحقة استخدامه في بناء نصوص الطلبات وتوليد مفاتيح التخزين المؤقت للصور. إن حساب مفتاح التخزين المؤقت قبل التحقق يعرض النظام لمخاطر تخزين مدخلات مكسورة أو خاطئة ناتجة عن استبدال الصفر بالقيم الافتراضية. وتجدر الإشارة هنا إلى أن توليد الطلبات الفعلية، وتجربة مفاتيح التخزين المؤقت، أو دعم تراتبية متعددة لمتغيرات البيئة تظل خطوات لاحقة خارج نطاق الاختبارات المنفذة في هذا العقد البرمجي.

احفظ عقد الإعدادات عندما يتغير المشروع

تعتبر إدارة التغيير في مخطط الإعدادات عملية دقيقة تتطلب مزامنة مستمرة بين كود التحقق ومصادر البيانات المخزنة مسبقاً. إذا طرأت تعديلات على المشروع تستوجب إضافة حقول جديدة أو تعديل نطاقات الحقول الحالية، فإن دالة merge_settings لا تقوم بترحيل الإعدادات القديمة أو ترقيتها تلقائياً. على سبيل المثال، إذا كانت هناك إعدادات قديمة مخزنة في قاعدة البيانات وتفتقر لحقل جديد أضيف إلى FIELDS، فإن تمريرها كأساس سيؤدي إلى فشل فوري في validate(base) برفع ValueError بسبب عدم تطابق الحقول.

يتطلب تحديث المخطط الانتباه إلى الفارق الجوهري بين استبدال القيمة الافتراضية لحقل ما وتجاوزها بواسطة رقعة التعديل. فلو قمنا بتغيير القيمة الافتراضية لحقل seed في الأساس من 7 إلى 42، فإن جميع الاستدعاءات التي ترسل رقعة فارغة ستعتمد القيمة الجديدة 42 تلقائياً. أما الاستدعاءات التي ترسل صراحة seed=0 فستظل محتفظة بالصفر دون تأثر بتغير القيمة الافتراضية، بفضل آلية الدمج المباشرة التي تعزل الإدخال الصريح عن التحولات التي تطرأ على القيم المبدئية للمشروع.

إذا حاول المطور إضافة بيانات وصفية داخل رقعة التعديل مثل تمرير رقم الإصدار {'schema_version': 2}، فإن كود الدمج الحالي سيرفض العملية فوراً ويعتبر schema_version حقلاً مجهولاً عبر فحص set(patch) – FIELDS. تفرض هذه الصرامة معالجة بيانات الإصدارات والترقية خارج دالة الدمج تماماً؛ بحيث تتولى دوال هجرة مخصصة قراءة الإصدار، وتكييف الحقول، وحذف البيانات الوصفية قبل تسليم القاموس النهائي لدالة الدمج المحلية.

يجب أن تخضع أي عمليات ترحيل مستقبلية أو إضافات للمخطط لاختبارات قبول مستقلة تثبت سلامة التحويل قبل دمجه في النظام العام. إن اجتياز الاختبارات الإحدى عشرة الحالية يبرهن فقط على دقة سلوك الكود المنفذ على الحقول الأربعة المسطحة prompt وwatermark وseed وstrength ضمن بيئة بايثون 3.12 المحلية، ولا يمنح حصانة دائمة للتعديلات الجديدة. الحفاظ على صلابة العقد البرمجي يستند إلى توثيق كل تعديل واختبار حالاته الحدية بدقة، لضمان بقاء الاختيارات الصريحة مثل False والصفر محفوظة في كل مرحلة من مراحل تطور المشروع.

اجعل استعادة الافتراضي عملية صريحة غير إرسال الصفر

يتطلب زر مقترح لاستعادة الإعداد الافتراضي معنى مختلفاً عن إرسال False أو0. لذلك أضيفت دالة reset_fields كامتداد محلي مستقل يتلقى defaults وcurrent وقائمة أسماء fields. لا تتلقى الدالة طلب متصفح ولا تعرف قيم خدمة صور خارجية؛ القواميس يزودها بها المستدعي. تفحص صحة قاموسي الافتراضيات والإعداد الحالي وفق العقد نفسه، وتتأكد من أن fields قائمة أسماء نصية معروفة وغير مكررة، ثم تبني رقعة تحتوي لكل اسم قيمته من defaults. أخيراً تطبق merge_settings على current بهذه الرقعة. هكذا لا نحمّل None معنى إعادة الضبط بعد أن عرّفه عقد seed كإدخال مرفوض.

في اختبار إعادة حقل واحد، يحتوي current على watermark=False وseed=0 وstrength=0، بينما تحمل defaults القيم True و7 و0.8. تمرير القائمة ['seed'] يعيد seed إلى7 ويترك watermark=False وstrength=0 كما هما. هذا فرق ملموس بين ثلاث عمليات: عدم إرسال seed يبقي الحالة الحالية، وإرسال seed=0 يختار الصفر، وطلب إعادة seed يستعمل الافتراضي المقدم. لا يختار المساعد أي مرحلة من هذه المراحل بالنيابة عن الواجهة. ينبغي أن تقرر واجهة مقترحة كيف يعبّر المستخدم عن إعادة الضبط وتحوّل اختياره إلى قائمة حقول صريحة، بدلاً من افتراض أن قيمة خادعة منطقياً تعني دائماً العودة إلى الأساس.

تختبر طريقتان إضافيتان أن الافتراضي نفسه قد يكون False أو0. في الأولى يصبح watermark في defaults مساوياً لـFalse بينما يساوي True في current؛ تعيد الاستعادة False كما ورد. وفي الثانية تصبح بذرة defaults صفراً وتعيدها الدالة بدلاً من استبدالها بسبعة. هاتان حالتان محليتان على القواميس، ولا تثبتان إمكان تعطيل علامة مائية في خدمة أو إعادة إنتاج صورة ببذرة معينة. المقصود حفظ معنى العملية في طبقة الإعدادات. ولأن الدالة ترجع قاموساً جديداً، تستطيع طبقة مقترحة عرض التغيير للمستخدم أو مقارنته بالحالة السابقة قبل الحفظ، لكن العرض والحفظ لم ينفذا في هذه التجربة.

تضم حزمة الامتداد ثماني طرق اختبار، إلى جانب إحدى عشرة طريقة للدمج، فيصبح مجموع التشغيل المشترك تسع عشرة طريقة. تختبر إعادة الحقل المختار، والافتراضي False، والافتراضي الصفري، والقائمة الفارغة التي تعيد نسخة مساوية وليست الكائن نفسه، ورفض اسم مجهول، ورفض اسم مكرر، ورفض تمرير نص بدلاً من قائمة، وعدم تعديل قاموسي الإدخال. تظل قيم الحقول مسطحة وأولية. لا يعني اختبار عدم التعديل أن الدالة تنشئ نسخة عميقة عامة أو أنها منسقة بين عدة مستخدمين؛ فمثل هذه المتطلبات تحتاج عقداً آخر وتزامناً واختبارات تخص التطبيق الذي يملك الإعدادات.

إذا تغيرت الافتراضيات من إصدار إلى آخر، تتوقف نتيجة reset_fields على defaults الذي زوّده المستدعي في ذلك الاستدعاء. الدالة لا تبحث عن أحدث إصدار، ولا تقرأ ملفاً ولا ترحل بيانات قديمة. حدد في التطبيق المقترح هل تعني الاستعادة افتراضيات الإصدار الذي بدأ به المشروع أم الافتراضيات الحالية، ثم اجعل القيمة المختارة ظاهرة في سياق العملية. لا تضف schema_version إلى رقعة الحقول الأربع دون تغيير العقد، لأن الحقل سيظل مرفوضاً. احتفظ بالنسختين من ملفات الكود وبالاختبارات عند إعادة التشغيل؛ فالامتداد يستورد validate وmerge_settings ولا يعيد تنفيذ قواعدهما. هذا يبقي التحقق من False والصفر واحداً في عمليتي التعديل والاستعادة.

أُعد المقال بمساعدة أدوات ذكاء اصطناعي ومراجعات تحريرية آلية. اختُبر المثال الأصلي محلياً ببيانات اصطناعية، دون تشغيل خدمة صور أو فيديو أو قياس نظام إنتاجي.

settings_reset.py

from settings_merge import validate, merge_settings, FIELDS

def reset_fields(defaults, current, fields):
    if not isinstance(defaults, dict) or not isinstance(current, dict):
        raise TypeError('Expected dictionaries')
    validate(defaults)
    validate(current)
    if not isinstance(fields, list) or any(not isinstance(field, str) for field in fields):
        raise TypeError('Expected a list of field names')
    if len(set(fields)) != len(fields) or set(fields) - FIELDS:
        raise ValueError('Unknown or repeated reset field')
    return merge_settings(current, {field: defaults[field] for field in fields})

نطاق التحقق المحلي: Eight new reset-helper methods plus eleven original merge methods,19total. Local flat dictionaries and selected field names only; no real UI, file persistence, provider parameters or image generation tested. Defaults are supplied by the caller, not discovered from files/environment. Reset and update are distinct operations; no network requests or automatic migrations.؛ البيئة: Python3.12.3 on Windows

التعليقات

كن أول من يعلّق على هذا المقال.

أضف تعليقاً

بريدك لن يُنشر. الحقول المطلوبة معلَّمة بنجمة.