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

صورتان بالاسم نفسه: ابن فهرس أصول وقارن نسختين دون خلط المسارات

مجلدان ورقيان مفتوحان يحملان صورتين لمزهريتين مختلفتين بجوار حاسوب وبطاقة مسطرة على مكتب خشبي
مجلدان ورقيان مفتوحان يحملان صورتين لمزهريتين مختلفتين بجوار حاسوب وبطاقة مسطرة على مكتب خشبي.

عند بناء فهرس بسيط لمجموعة مدخلات تحتوي على الزوجين front/product.png مع تسعة بايتات تجريبية fixture-a وback/product.png مع تسعة بايتات fixture-b، ينتج عن دالة broken_manifest قاموس بمفتاح واحد فقط هو product.png يحمل البصمة السداسية للمدخل الثاني بعد الكتابة فوق المدخل الأول. لم تطرح الدالة أي استثناء ولم تفحص تعارض المفاتيح، بل تسببت في إخفاء سجل كامل داخل الذاكرة لمجرد أن المكون الأخير في المسارين متطابق. تظهر هذه النتيجة العيب الصريح للاعتماد على الاسم المجرد بدلاً من تمثيل المسار النسبي كاملاً، حيث يتطلب العمل الهندسي الاحتفاظ بكل مسار منطقي مستقلاً جنباً إلى جنب مع طول البيانات بالبايت وتمثيل خوارزمية التجزئة دون اختزال السجلات.

شاهد تصادم الاسم ثم ابن سجلاً لكل مسار

يقدم كود asset_manifest.py وظيفة make_manifest لتصحيح هذا الاختزال، حيث تستقبل قائمة من أزواج المسارات والبيانات الثنائية وتعيد قائمة صريحة من القواميس. في الاختبار المحدد، ينتج عن تمرير الزوجين front/product.png وback/product.png سجلان مستقلان، يحتوي كل سجل على ثلاثة حقول دقيقة هي path وbytes وsha256. لم يتوقف التنفيذ ولم يحدث تصادم في المفاتيح، لأن البنية الناتجة قائمة مرتبة تحتفظ بترتيب الإدخال وتمنح كل مسار تمثيلاً فريداً. يضمن هذا الفصل الصريح عدم استبدال سجل بآخر، مما يتيح للأنظمة اللاحقة فحص الحجم المكون من تسعة بايتات والبصمة السداسية الناتجة عن بايتات fixture-a دون أن تتأثر بالسجل الآخر الخاص ببايتات fixture-b.

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

ينتج كل سجل حقلاً path وحقل bytes وحقل sha256. الحجم عدد صحيح غير سالب، وليس موجباً حصراً؛ فالدالة تستطيع حساب طول كتلة بايتات فارغة وإن لم تتضمن المجموعة الحالية طريقة اختبار منفصلة لهذه الحالة. أما قيمة sha256 فهي تمثيل سداسي عشري بطول 64 محرفاً. اختر أسماء الحقول كما هي عند بناء مستهلك للفهرس، ولا تستبدل bytes بعدد المحارف النصية أو بعدد البكسلات. الحقلان الأخيران يصفان المدخل الثنائي المعطى فقط. وجود اسم ينتهي بـ png لا يضيف إلى القاموس عرضاً أو ارتفاعاً أو قناة شفافية، ولا يثبت أن البايتات قابلة للفتح بصورة. يحتاج كل مطلب من هذه المطالب إلى مرحلة فحص أخرى لها مدخلات واختبارات مستقلة.

asset_manifest.py

from pathlib import PurePosixPath
import hashlib

def broken_manifest(items):
    return {PurePosixPath(name).name: hashlib.sha256(data).hexdigest()
            for name, data in items}

def logical_name(name):
    if not isinstance(name, str) or not name or '\\' in name or ':' in name:
        raise ValueError('Use a nonempty POSIX-style logical path')
    parts = name.split('/')
    if any(part in ('', '.', '..') for part in parts):
        raise ValueError('Empty and dot segments are not allowed')
    return str(PurePosixPath(name))

def make_manifest(items):
    result = []
    seen = set()
    for name, data in items:
        name = logical_name(name)
        if name in seen:
            raise ValueError('Duplicate logical path')
        if not isinstance(data, bytes):
            raise TypeError('This example accepts bytes only')
        seen.add(name)
        result.append({'path': name, 'bytes': len(data),
                       'sha256': hashlib.sha256(data).hexdigest()})
    return result

نطاق التحقق المحلي: Ten local unittest methods against synthetic byte literals that are not PNG images. No filesystem scan, image decoding, upload, archive extraction, path confinement/security sandbox, duplicate-content detection or overwrite test was performed. Paths are logical POSIX-style identifiers; this is not a converter for arbitrary real Windows filenames. Rerun as test_original.py on2026-10-30 alongside ten new diff methods; the new suite log is supplied.؛ البيئة: Python3.12.3 on Windows

اتفق على هوية منطقية قبل ربطها بقرص حقيقي

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

تتيح المسارات النقية معالجة مكونات الاسم دون إجراء وصول إلى نظام الملفات، ويعيد name المكون الأخير من المسار. Python3.12 pathlib: pure paths

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

تحديد هوية طلب الصور قبل التخزين المؤقت يسبق إنتاج الأصل، بينما يصف هذا الفهرس السجل المنطقي للبايتات بعد توفرها. بصمة الطلب واسم الأصل وبصمة المحتوى حقول تؤدي أدواراً مختلفة.

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

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

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

اقرأ الحجم والبصمة دون تحميلهما معنى غير موجود

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

في المدخل الأصلي، fixture-a وfixture-b سلسلتا بايتات اصطناعيتان طول كل منهما تسعة بايتات، وليستا صورتين. تذكر ذلك عند إعادة المثال في مشروع صور: نحن ندرس هوية سجلين يحملان اسم الملف الأخير نفسه، ولا نقيس جودة صورتين أو صلاحية تنسيقهما. تمرر make_manifest البايتات مباشرة إلى hashlib.sha256 وتحفظ hexdigest الناتج، دون فك ترميز صورة أو قراءة ترويسة. يمكنك تبديل هذه البايتات بمدخلات اختبار أخرى لدرس سلوك الفهرس، لكن ذلك يكون تجربة جديدة تحتاج نتائجها الخاصة. وحتى إذا وفرت لاحقاً ملف PNG حقيقياً، فلن يصبح الفهرس أداة فحص صور بمجرد تغير نوع البيانات التي يمثلها الاسم؛ سيظل ينفذ حساب الطول والتجزئة نفسيهما.

تساوي نصي البصمتين ليس برهاناً رياضياً على تطابق كل بايت، ولا مصادقة على مصدر المحتوى. وفي هذه التجربة نعرف أن مدخلي b'A' في اختبار المسارين المتشابهين متطابقان لأن الاختبار يمرر القيمة نفسها، لا لأننا استنتجنا هذه الحقيقة من البصمة وحدها. أما اختلاف بصمتين محسوبتين من مدخلين فهو دليل على اختلاف المدخلين في سياق الحساب، دون أن يفسر سبب الفرق أو قيمته البصرية. لا تستنتج أن كل تعديل ممكن ينتج بالضرورة بصمة مختلفة، ولا أن صورة محفوظة بضغط آخر جرى اختبارها هنا. إن احتاج تطبيقك إلى مقارنة بايتية مباشرة أو إلى تحليل بصري، فعرّف المطلوب ونفذه في مرحلة أخرى بدلاً من توسيع معنى حقل sha256.

لا يسجل هذا المخطط أبعاد الصورة أو EXIF أو نوع القنوات أو صلاحية الترويسة. لذلك لا تستخدم وجود صف في الفهرس شرطاً وحيداً لعرض صورة للمستخدم أو لقبولها في مسار نشر. تستطيع طبقة مستقلة أن تفك ترميز الملف وتعيد تقرير أبعاد مثلاً، ثم تقرر كيف تربط التقرير بمسار الأصل وإصدار محتواه. لم تُنفذ هذه الطبقة في الشيفرة الحالية ولم تُشغّل لها اختبارات. الفصل المفيد هنا هو وضوح المدخل: make_manifest تتلقى بايتات جاهزة واسماً منطقياً؛ أما checked_index فتتلقى سجلات جاهزة ولا تتلقى البايتات أصلاً. لا ينبغي أن تنسب إلى الدالة الثانية معرفة لا توجد في معاملاتها، حتى لو جاء السجل من مصدر تعتقد أنه موثوق.

احتفظ بدلالة الحقول عند نقل الفهرس بين مكونات المشروع. لا تغيّر bytes إلى نص مثل "9 bytes" إذا كنت تريد تمريره إلى checked_index، ولا تختصر البصمة للعرض ثم تعيد استعمال النص المختصر في المقارنة. يمكن لواجهة مقترحة أن تعرض نسخة مختصرة للقارئ مع الاحتفاظ بالقيمة الأصلية في بياناتها، لكن الواجهة لم تُبن في هذا المثال. ولا يوجد قياس يثبت أن الفهرس سريع أو مقتصد في الذاكرة لأحجام كبيرة؛ المدخلات والسجلات موجودة كلها في الذاكرة هنا. إذا كان حجم الأصول هو المشكلة الفعلية، فحدد حدود الذاكرة المطلوبة وطريقة القراءة والقياس قبل اختيار هذا التمثيل كجزء من نظام أكبر.

قارن فهرسين إلى أربع مجموعات محددة

تعتمد دالة compare_manifests في ملف manifest_diff.py على مطابقة المسارات المنطقية بين فهرسين مدققين لتوزيع النتائج على أربع فئات منفصلة. لا تعيد الدالة حساب البصمات من القرص ولا تفحص أصولاً فعلية، بل تقارن السجلات النصية والعددية الممرة إليها داخل الذاكرة. يتم أولاً استدعاء checked_index لتحويل قائمتي الفهرس إلى قاموسين يربطان كل مسار بزوج يتألف من الحجم والبصمة، ثم تُستخدم العمليات الحسابية للمجموعات في بايثون لتحديد المسارات المضافة والمزالة والمشتركة، مما ينتج قاموساً موحداً يحتوي على أربع قوائم من المسارات النصية.

يوضح الاختبار المنفذ test_four_groups هذا التقسيم بدقة عملية عبر حالتين محددتين. يتضمن الفهرس الأول keep/a.png بالبايت b'A'، وchange/a.png بالبايت b'B'، وgone/a.png بالبايت b'C'. أما الفهرس الثاني فيتضمن keep/a.png بنفس البايت b'A'، وchange/a.png بالبايت b'D'، وnew/a.png بالبايت b'E'. عند مقارنة الفهرسين، تصنف الدالة المسار new/a.png ضمن مجموعة added، والمسار gone/a.png ضمن مجموعة removed، والمسار change/a.png ضمن مجموعة changed لاختلاف البايتات، والمسار keep/a.png ضمن مجموعة unchanged لتطابق الحجم والبصمة.

تجري المقارنة بين الأزواج المخزنة تحت كل مسار مشترك عبر التعبير البرمجي old[path] == new[path]، الذي يتحقق من تطابق حقل الحجم والبصمة السداسية معاً في خطوة واحدة. إذا اختلف الحجم أو اختلفت البصمة، يُدرج المسار في قائمة changed، بينما يوضع في قائمة unchanged إذا تطابقت القيمتان بالكامل. تعتمد هذه الخطوة حصراً على البيانات المخزنة مسبقاً في السجلين، دون فحص ما إذا كان التغير يمثل تحديثاً حقيقياً أو خطأ في نقل البيانات، مما يترك للمستهلك اللاحق مسؤولية تفسير دلالة التغيير المرصود بين النسختين.

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

manifest_diff.py

from asset_manifest import logical_name
import re

def checked_index(rows):
    index = {}
    for row in rows:
        if not isinstance(row, dict) or set(row) != {'path', 'bytes', 'sha256'}:
            raise ValueError('Expected exactly path, bytes and sha256')
        path = logical_name(row['path'])
        size, digest = row['bytes'], row['sha256']
        if type(size) is not int or size < 0:
            raise ValueError('Size must be a nonnegative integer')
        if not isinstance(digest, str) or re.fullmatch('[0-9a-f]{64}', digest) is None:
            raise ValueError('Expected a lowercase SHA256 representation')
        if path in index:
            raise ValueError('Duplicate logical path')
        index[path] = (size, digest)
    return index

def compare_manifests(before, after):
    old, new = checked_index(before), checked_index(after)
    common = old.keys() & new.keys()
    return {
        'added': sorted(new.keys() - old.keys()),
        'removed': sorted(old.keys() - new.keys()),
        'changed': sorted(path for path in common if old[path] != new[path]),
        'unchanged': sorted(path for path in common if old[path] == new[path]),
    }

نطاق التحقق المحلي: Ten new unittest methods for a pure in-memory manifest comparison, plus the ten original manifest methods rerun in the same directory. Bytes are synthetic literals, not images. Validates record shape and representation but does not recompute supplied hashes against files. Added/removed do not infer rename, deletion, jobs or disk effects. No writer, filesystem traversal, checkpoint, image decoding or remote API.؛ البيئة: Python3.12.3 on Windows

تتبع حالة نقل اسم وحالة تساوي المحتوى

تتعامل خوارزمية المقارنة مع عمليات نقل الملفات أو إعادة تسميتها كإجراءين مستقلين تماماً، حيث يظهر المسار القديم في قائمة removed بينما يظهر المسار الجديد في قائمة added. يثبت الاختبار المنفذ test_move_is_not_inferred هذا السلوك عملياً؛ فعند مقارنة فهرس يحتوي على old.png ببايتات b'A' مع فهرس آخر يحتوي على new.png بنفس البايتات تماماً، تعيد الدالة removed بقيمة ['old.png'] وadded بقيمة ['new.png'] مع بقاء changed وunchanged فارغتين. لا تحاول الدالة استنتاج حدوث نقل، بل تلتزم بالهوية المبنية على المسار فقط.

يمتد هذا المبدأ ليشمل وجود ملفين بمسارين مختلفين ومحتوى بايتي متطابق داخل الفهرس نفسه. يوضح الاختبار test_same_content_different_paths أن تمرير المسارين a.png وb.png مع بايتات متطابقة b'A' ينتج فهرساً بسجلين مستقلين تماماً، وتقبل checked_index قائمة السجلات الناتجة وتبني منها قاموساً طوله اثنان. لا تقوم الدالة بإلغاء التكرار أو دمج السجلات المتشابهة المحتوى، لأن كل مسار منطقي يمثل أصلاً منفرداً له دوره المستقل في المنظومة، وتطابق التجزئة لا يبرر إخفاء أي مسار مصرح به في المدخلات.

يفحص الاختبار الأصلي test_changed_bytes_change_hash بصمتي b'a' وb'b' تحت الاسم a.png ويتأكد من اختلافهما. لا يستدعي هذا الاختبار compare_manifests ولا يتحقق بنفسه من قائمة changed؛ تلك خطوة مختلفة يغطيها test_four_groups عند تبديل b'B' إلى b'D' للمسار change/a.png. الفصل بين التأكيدين يجعل سجل التجربة قابلاً للقراءة: لدينا فحص لحساب التجزئة على قيمتين محددتين، وفحص آخر لتصنيف فرق سجلين. لا تحوّل نجاح الأول إلى ادعاء أن كل تغيير محتمل كُشف، ولا تسم الثانية اختباراً لقراءة ملفات. إنما تتعاون الدوال في مشروع صغير لأن كل دالة تتلقى العقد الذي تعيده الدالة السابقة، مع بقاء التأكيدات المحلية واضحة.

تحسب hashlib.sha256 بصمة من البايتات المعطاة، ويعرض hexdigest تمثيلها السداسي؛ البصمة ليست تشفيراً لمحتوى الصورة. Python3.12 hashlib: SHA256

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

ارفض فهرساً ناقص العقد قبل حساب الفرق

تفرض دالة checked_index عقداً صارماً على بنية السجلات في الفهرس، حيث تشترط أن يكون كل صف عبارة عن قاموس يحتوي بدقة على المفاتيح الثلاثة {'path', 'bytes', 'sha256'} دون أي نقص أو زيادة. يوضح الاختبار test_extra_field أن إضافة مفتاح إضافي مثل mime بقيمة 'image/png' يؤدي فوراً إلى طرح استثناء ValueError، ورفض الفهرس بأكمله. يحمي هذا الفحص الشكلي النظام من استهلاك هياكل بيانات غير قياسية أو غير متوقعة، ويضمن توافق جميع الصفوف مع البنية المتفق عليها قبل إجراء أي مقارنة.

تفحص الدالة حقل الحجم للتأكد من أنه عدد صحيح لا يقل عن الصفر، مع استخدام الفحص الصريح type(size) is not int لرفض القيم المنطقية. يختبر test_bool_size تمرير القيمة True في حقل الحجم، والتي تُعد فرعاً من الأعداد الصحيحة في بايثون ولكنها غير مقبولة كحجم بيانات، مما يؤدي إلى طرح استثناء ValueError. كما تطبق الدالة تعبيراً نمطياً صارماً re.fullmatch('[0-9a-f]{64}', digest) للتحقق من أن حقل sha256 يتكون بدقة من أربعة وستين محرفاً سداسياً عشرياً بصيغة الأحرف الصغرى، رافضة أي رموز غير مطابقة.

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

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

ما الذي فحصته طرق الاختبار العشرون فعلاً؟

شُغلت عشرون طريقة اختبار unittest محلياً: عشر طرق أصلية في test_original.py وعشر طرق جديدة في test_example.py. يعتمد ملف المقارنة على asset_manifest.py، لذلك ينبغي الاحتفاظ بالملفين عند إعادة التشغيل، ثم استخدام اكتشاف الاختبارات بنمط test_*.py في مجلدهما. لا تعني نتيجة التشغيل أن ملفات PNG فُتحت أو أن مجلداً حقيقياً جرى مسحه؛ فقد عالجت الطرق بايتات اصطناعية وسجلات داخل الذاكرة. سُجلت البيئة Python 3.12.3 على Windows وحُفظ المصدر وبصمته ونتيجة التنفيذ. زمن مشغل الاختبارات لا يستخدم هنا للمقارنة بين أدوات أو لادعاء أداء إنتاجي. الأهم للقارئ هو المدخل الذي مرره كل اختبار والتأكيد الذي فحصه، لا العدد المجرد للطرق الناجحة.

تغطي الطرق العشر الأولى المنتمية لفئة ManifestTests جوانب بناء الفهرس والتحقق من المسارات. اختبرت test_broken_basename_collision تقلص القاموس المعيب إلى عنصر واحد عند تمرير مسارين يحملان الاسم product.png، بينما أثبتت test_keep_relative_identity احتفاظ make_manifest بالمسارين كاملين. وفحصت test_duplicate_exact_path رفض المسارات المتطابقة، بينما تحققت test_dot_segments عبر ثلاث حالات فرعية subTest من رفض المقاطع النقطية مثل ../a.png وx/./a.png وx/../a.png، إلى جانب فحص رفض المسار المطلق والشرطات العكسية ورفض البيانات غير الثنائية.

تولت فئة DiffTests فحص مقارنة الفهارس عبر عشر طرق جديدة، شملت test_four_groups للتحقق من تصنيف المجموعات الأربع بدقة، وtest_move_is_not_inferred لإثبات عدم استنتاج النقل، وtest_same_content_different_paths لإثبات قبول مسارين مختلفين بمحتوى متطابق. كما فحصت test_empty التعامل مع القوائم الفارغة، واختبرت test_duplicate_row وtest_extra_field وtest_bool_size وtest_bad_digest رفض الصفوف المخالفة للعقد، إضافة إلى test_sorted_and_inputs_unchanged التي أكدت ترتيب المخرجات وسلامة المدخلات، وtest_single_backslash لفحص الشرطة العكسية.

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

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

سلّم تقرير فرق للقارئ التالي دون تنفيذ حذف تلقائي

تُنهي دالة compare_manifests مهمتها بإرجاع قاموس بسيط يحتوي حصراً على أربع قوائم من المسارات النصية المرتبة، وهي added وremoved وchanged وunchanged. لا يتضمن هذا القاموس أي تفاصيل إضافية مثل حجم الملفات أو بصماتها السداسية أو تواريخ تعديلها، كما أنه لا ينفذ أي أوامر لحذف الملفات أو تعديلها على وسائط التخزين. يقتصر دور المقارنة على تقديم هذا التقرير النصي المجرد لمستهلك لاحق يتولى بنفسه اتخاذ القرارات التشغيلية وفقاً لسياق الاستخدام المحدد، دون أي تدخل تلقائي من أداة المقارنة.

إذا كان المكون المستهلك بحاجة إلى معرفة الحجم أو البصمة المرتبطة بأحد المسارات في التقرير، فيجب عليه الرجوع مباشرة إلى الفهرسين الأصليين before وafter اللذين جرت مقارنتهما. فعلى سبيل المثال، لمعرفة حجم ملف أُدرج ضمن قائمة added، يقوم المستهلك بالبحث عن مساره داخل قائمة الفهرس الجديد لاستخراج حقل bytes الخاص به. هذا الفصل يمنع تضخم حجم تقرير المقارنة بالبيانات المكررة، ويجعل هيكل الناتج خفيفاً وسهل المعالجة في طبقات المراقبة أو العرض التي لا تحتاج سوى لمعرفة أسماء المسارات المتأثرة.

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

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

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

التعليقات

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

أضف تعليقاً

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