سجل JSONL توقف في آخر سطر: اقرأ المكتمل واحتفظ بالذيل دون إصلاح صامت
تستقبل المعالجة في هذا الشرح مدخلاً ثنائياً محدداً في الذاكرة بصيغة b'{"id":"a"}\n{"id":'، حيث يفصل بايت السطر الجديد LF السجل الأول المكتمل عن بداية سجل ثانٍ لم يكتمل بعد. عند تمرير هذه السلسلة إلى دالة القراءة الآمنة، تُرجع الدالة أربعة حقول صريحة: قائمة السجلات وتضم كائناً وحيداً هو {'id': 'a'}، وحقل committed_bytes بقيمة أحد عشر بايت، وحقل held_tail الذي يحتفظ بالبايتات المتبقية b'{"id":' دون تفكيك، وحقل next_line بقيمة اثنين للإشارة إلى موضع السطر التالي. هذا الإجراء يتجنب الانهيار المفاجئ الذي تسببه محاولة فك ترميز النصوص المنقوصة، ويرفض في الوقت نفسه التخمين الساذج بإغلاق الأقواس آلياً. يركز هذا العمل على قرارات التصميم داخل سجل تتبع معالجة صور افتراضي يقرأ كتل بايتات معزولة داخل الذاكرة.
ابدأ من البايت الذي لم يكتمل بعد
تبدأ broken_read بفك ترميز كامل الدخل بصيغة UTF-8، ثم تستعمل splitlines لتقسيم النص، وتطبق json.loads على كل سطر داخل قائمة استيعابية. في المدخل الاصطناعي المحدد ينجح تحليل السطر الأول، ثم يثير السطر الأخير غير المكتمل JSONDecodeError، فلا تعيد الدالة القائمة إلى مستدعيها. لا يثبت هذا الاختبار وقوع عطل في ملف حقيقي أو فقدان سجل محفوظ؛ إنه يوضح كيف يمنع خطأ التحليل إرجاع نتيجة الاستدعاء. يتجنب البديل تحليل الجزء غير المنتهي بـ LF، بينما يبقى رفض السطر المكتمل الفاسد قراراً مستقلاً. ينبغي أن يحدد تطبيقك الفرق بين هذين النوعين من المدخلات قبل أن يقرر هل ينتظر مزيداً من البايتات أم يعرض خطأً للمشغل.
في المقابل، تتعامل دالة read_complete_records مع الدخل بصفته كائناً ثنائياً من نوع bytes حصراً، وتبدأ بتقسيمه بالاعتماد على بايت السطر الجديد المفرد b'\n'. هذا التقسيم يفرز السجلات التي تنتهي بهذا الفاصل عن الجزء الأخير الذي لم يتلق الفاصل بعد، والذي يُعزل مباشرة داخل المتغير parts[-1]. السجل الأول b'{"id":"a"}\n' يُعاد تركيبه مع فاصل السطر لفك ترميزه عبر الترميز المعتمد UTF-8 واختبار بنيته بدقة، بينما يُحتجز الذيل الخام b'{"id":' في حقل منفصل دون محاولة إخضاعه لمحلل النصوص، مما يلغي التوقف القسري لمجرد عدم اكتمال الشحنة الأخيرة.
النتيجة التي تعيدها الدالة للمدخل المذكور تحدد committed_bytes بالقيمة أحد عشر، وهي الطول البايتي الدقيق للسجل الأول المقبول مضافاً إليه بايت الانتقال السطري. هذا الرقم لا يمثل إثباتاً لكتابة مستقرة على وسيط تخزين دائم ولا يُعد نقطة استئناف كونية للمستهلك الخارجي، بل هو مجرد طول البادئة المقبولة من مصفوفة البايتات الحالية الممررة في الذاكرة. احتجاز الذيل يمنح المستدعي مرونة التعامل مع البايتات المتبقية دون فرض أي تعديل أو فك ترميز استباقي عليها، مما يحمي النظام من افتراضات الحفظ غير المؤكدة.
عرّف حدود السجل قبل محاولة فك JSON
تؤكد وثائق مكتبة json الرسمية في بايثون أن تنسيق JSON ليس بروتوكولاً مؤطراً بذاته، مما يعني أن تتابع كائنات JSON المتعددة داخل مجرى تدفق واحد لا ينتج مستنداً صالحاً يمكن فكه ككتلة واحدة عبر استدعاء موحد. لهذا السبب يفرض مشروع سجل صورنا الاصطناعي بنية السطر الواحد JSONL كإطار تأطير خارجي مستقل، حيث يعمل بايت السطر الجديد LF كحد صارم يفصل السجلات المستقلة. كل سطر مكتمل يجب أن يُقرأ ويُفحص ككيان منفصل، بدلاً من التعويل على قدرة المحلل النحوي على استنتاج نهايات الكائنات بصورة ضمنية.
توضح وثائق json أن JSON ليس بروتوكولاً مؤطراً؛ تكرار dump إلى المجرى نفسه لا ينشئ تلقائياً مستند JSON صالحاً واحداً. يختار تطبيقنا تنسيق سجل لكل سطر بدلاً من افتراض حدود مدمجة. Python3.12 json decoder
تعتمد دالة التحقق داخل القارئ على معايير صلبة لكل سطر مكتمل: يجب أن ينجح فك ترميزه كـ UTF-8، وأن يقبله json.loads الافتراضي، وأن يكون الناتج قاموساً من نوع dict يحتوي على مفتاح id من نوع سلسلة نصية غير فارغة. إذا غاب المفتاح أو كان فارغاً، تطلق الدالة خطأ صريحاً من نوع RecordError. ومع ذلك، هناك حدود برمجية لم تُبنَ لها قيود إضافية في هذا النموذج المحلي؛ فالسلسلة النصية المكونة من مسافات بيضاء فقط مثل " " تُعد نصاً غير فارغ وفق شرط الدالة الحالي وتُقبل، كما أن محلل JSON الافتراضي لا يمنع تكرار المفاتيح داخل السطر الواحد.
يشرح فحص CSV العربي والفاصل كيف تتسبب افتراضات حدود الحقول في خطأ مختلف. لا تنقل قواعد CSV إلى JSONL؛ عرّف لكل تنسيق حد السجل وطريقة ترميزه قبل بناء المستهلك.
يتطلب المنطق المعتمد أن يكون المدخل الثنائي من فئة bytes حصراً، حيث تطلق الدالة استثناء TypeError فوراً عند تمرير نص عادي مثل 'text'. هذا الإلزام يضمن عدم قيام بيئة التشغيل بأي فك ترميز عشوائي قد يغير إزاحات المؤشرات قبل التعرف على بايت السطر الجديد. فك ترميز النصوص قبل التجزئة قد يتسبب في احتساب مواضع الرموز النصية المحارف بدلاً من البايتات الفعلية، وهو ما يدمر دقة تتبع المؤشر عند معالجة محارف متعددة البايتات كالتي تستخدم في أسماء ملفات الصور أو أوصافها.
تتجنب الدالة محاولة إكمال الأقواس الناقصة أو تصحيح الصياغة في الذيل المحتجز بقرار تصميمي متعمد؛ فالإصلاح الصامت داخل طبقة القراءة يخفي عادة أخطاء البرامج الكاتبة أو حالات الإرسال المبتور. إذا أُغلق القوس عشوائياً، قد يُسجل كائن ناقص كأنه عملية معالجة صور مكتملة، مما يفسد البيانات في الطبقات اللاحقة. يقتصر دور القارئ على التحقق البنيوي الصارم لما اكتمل بالفعل، مع إعادة ما تبقى بحالته الخام تماماً دون تدخل تفسيري أو ترميمي.
jsonl_tail.py
import json
class RecordError(ValueError):
pass
def broken_read(data):
return [json.loads(line) for line in data.decode('utf-8').splitlines()]
def read_complete_records(data):
if not isinstance(data, bytes):
raise TypeError('Expected bytes')
offset = 0
rows = []
parts = data.split(b'\n')
for number, part in enumerate(parts[:-1], 1):
line = part + b'\n'
try:
row = json.loads(line.decode('utf-8'))
if not isinstance(row, dict) or not isinstance(row.get('id'), str) or not row['id']:
raise ValueError('Expected a record with a nonempty string id')
except (ValueError, UnicodeError) as exc:
raise RecordError(f'Invalid complete record at line {number}, byte {offset}') from exc
rows.append(row)
offset += len(line)
return {'records': rows, 'committed_bytes': offset,
'held_tail': parts[-1], 'next_line': len(parts)}
نطاق التحقق المحلي: Twelve unittest methods on synthetic in-memory JSONL bytes. Only LF marks a complete record; CRLF is accepted and counted. Tail is held even when syntactically valid JSON without newline. No disk truncation, write, append concurrency, crash simulation, durable commit, duplicate-ID handling, resume consumer or automatic repair. Full input is already in memory; no streaming or memory bound. Newline is a reader boundary chosen for this application, not proof of a durable committed write.؛ البيئة: Python3.12.3 on Windows
اقرأ نتيجة القارئ واحتفظ بالذيل نفسه
عند اكتمال تحليل شحنة البايتات بنجاح، يُرجع القارئ قاموساً يحتوي على أربعة مفاتيح محددة: records ويضم السجلات المقبولة كقواميس بايثون، وcommitted_bytes ويعبر عن الإزاحة البايتية التراكمية، وheld_tail ويحوي البايتات التي لم تنتهِ بفاصل سطري، وnext_line ويحدد رقم السطر المنطقي التالي للمعالجة. ففي حالة الدخل الفارغ تماماً b''، تكون قائمة السجلات فارغة، وcommitted_bytes صفراً، والذيل فارغاً b''، بينما يُضبط next_line على القيمة واحد، مما يعكس بدقة عدم وجود أي أسطر مكتملة داخل الكتلة المعطاة.
إذا انتهى المدخل الثنائي بفاصل سطر جديد نظامي، كأن نمرر السجل b'{"id":"a"}\n'، فإن تجزئة البايتات split(b'\n') تُنتج جزءاً أخيراً فارغاً. يُعامل هذا الجزء الفارغ كذيل محتجز بقيمة b'' دون إطلاق أي خطأ، وتُعاد قائمة تحتوي على السجل المكتمل، وتستقر committed_bytes عند أحد عشر بايت، ويرتفع next_line إلى اثنين. يتيح هذا السلوك للمستدعي معرفة أن الشحنة تمت معالجتها بالكامل دون بقايا معلقة تتطلب الدمج مع الدفعة اللاحقة.
أما إذا كان المدخل نصاً نحوياً صحيحاً في لغة JSON ولكنه غير متبوع بفاصل سطري، مثل b'{"id":"a"}'، فإن القارئ لا يقبله كسجل مكتمل على الإطلاق. وفق قواعد الفرز المطبقة، ينتهي الأمر بهذه الكتلة بأكملها داخل held_tail، بينما تظل قائمة السجلات فارغة وتستقر committed_bytes عند الصفر، ويكون next_line مساوياً لواحد. يوضح هذا السلوك الحاسم أن صحة JSON النحوية ليست كافية لاجتياز القراءة؛ إذ يُعد فاصل السطر الصريح LF شرطاً إلزامياً لاعتبار السجل جاهزاً للاستهلاك.
في سيناريو تدفق البايتات المجزأ، كما أثبت الاختبار باقتران السلسلة b'{"id":"a"}\n{"id":' باللاحقة b'"b"}\n'، يستطيع النظام إعادة تجميع السجل الثاني بنجاح بمجرد اكتمال حدوده السطرية. عند تمرير المجموع المركب، تعيد الدالة سجلين مكتملين هما {'id': 'a'} و{'id': 'b'}، مع تصفير الذيل المحتجز ورفع العداد البايتي إلى الطول الكلي. هذا التحقق يؤكد قدرة المستدعي على متابعة القراءة السلسة إذا قام بضم الذيل القديم إلى التدفق الجديد يدوياً دون الحاجة لأي منطق ترقيع استثنائي.
فرّق بين ذيل محتجز وسطر مكتمل فاسد
يميز التصميم بصرامة بين الذيل الذي لم تنتهِ بايتاته بفاصل سطري بعد، وبين السطر المكتمل بنيوياً الذي يختتم بـ LF لكنه يحتوي على بيانات تالفة. الذيل المحتجز يُعامل كحالة تدفق معلقة طبيعية لا توقف البرنامج، في حين يُعامل السجل المكتمل المعطوب كخطأ فادح يمنع استمرار العملية برمتها. الخلط بين هاتين الحالتين قد يؤدي إما إلى تجاهل فساد في البيانات المخزنة، أو إلى إسقاط بايتات سليمة كانت فقط تنتظر اكتمال إرسالها.
عندما يواجه القارئ سطراً مكتملاً يحتوي على نص لا يمكن فكه، كما في الاختبار b'{"id":"a"}\nbroken\n{"id":"c"}\n'، تفشل دالة json.loads في السطر الثاني. هنا تطلق الدالة فوراً استثناء RecordError يحدد موضع العطل بنص صريح: 'Invalid complete record at line 2, byte 11'. تجدر الإشارة بدقة إلى أن الإزاحة البايتية المذكورة تشير إلى بداية السجل المعطوب داخل المصفوفة وليس إلى موقع الحرف التالف تحديداً داخله، مما يمنح المستدعي إحداثيات دقيقة لنقطة انطلاق السجل المرفوض.
يتبع القارئ السلوك الصارم نفسه عند مواجهة عيوب أخرى في السطور المكتملة؛ فالسطر الفارغ b'\n' يثير استثناء RecordError لأنه لا يحتوي على كائن JSON صالح، وتمرير بايت غير صالح لترميز UTF-8 متبوعاً بفاصل مثل b'\xff\n' يثير RecordError أيضاً بسبب UnicodeError الكامن. كذلك فإن السطور التي تفك إلى عناصر غير القواميس، مثل مصفوفة b'[]\n'، تُرفض صراحة لعدم مطابقتها لشرط التحقق البنيوي الخاص بوجود قاموس يحمل المفتاح id المطلوب.
عند إخفاق سجل مكتمل، ترفع الدالة الاستثناء ولا تعيد بادئة مقبولة ضمن قيمة نجاح جزئية. مثلاً لا يحصل المستدعي على السجل a من الاستدعاء الذي يتضمن بعده broken ثم LF. هذا يصف واجهة الإرجاع فقط: ليست الدالة معاملة على قاعدة بيانات، ولا تتراجع عن آثار نفذها مستهلك في استدعاءات سابقة. ومن الممكن بناء قارئ آخر يسلّم سجلات تباعاً، لكن عليه عندئذ تعريف معنى الفشل بعد تسليم بعضها. في هذا المثال اختير جمع النتيجة ثم إرجاعها، ولذلك يحتاج المستدعي إلى معالجة RecordError قبل اعتماد أي قيمة معادة من هذا الاستدعاء. لا تستنتج من هذا الاختيار ضمان اتساق لنظام خارجي لم يختبر هنا.
في المقابل التام، فإن الذيل المحتجز الذي لا ينتهي بـ LF لا يخضع لأي تحقق بنيوي أو فك ترميز، وبالتالي لا يثير أي استثناء حتى لو كان يشتمل على بايتات عشوائية أو غير متوافقة مع JSON. يظل الذيل مخزناً كبايتات صافية في انتظار الشحنة التالية، حيث يُترك الحكم النهائي عليه إلى اللحظة التي يكتمل فيها السطر بفاصل صريح. هذا الفصل يعزل طبقة القراءة عن اتخاذ قرارات مبكرة بناءً على بيانات غير كاملة التكوين.
احسب الموضع بالبايتات مع LF وCRLF
تعتمد الدالة على حساب الإزاحات التراكمية بالبايتات الصافية بدلاً من الاعتماد على عدد المحارف النصية لضمان دقة المؤشرات عبر الأنظمة المختلفة. في الاختبار المطبق على السجل b'{"id":"a"}\n' المنتهي بفاصل LF أحادي، تبلغ الإزاحة الناتجة 11 بايت، بينما يرتفع الرقم بدقة إلى 12 بايت عند تمرير السجل ذاته بنهاية سطر ثنائية متوافقة مع أنظمة ويندوز b'{"id":"a"}\r\n'. هذا الفرق يعكس احتساب بايت الإرجاع carriage return ضمن طول السجل قبل الانتقال للسطر التالي.
تتحقق هذه المعالجة بفضل عملية التقسيم عبر data.split(b'\n') وإعادة دمج الفاصل لاحقاً كـ line = part + b'\n'؛ حيث يبقى بايت b'\r' ملتصقاً بنهاية المتغير part فيُحتسب ضمن طول السجل len(line). وحيث إن محلل json.loads يتجاهل المسافات الفارغة ورموز التحكم البيضاء المحيطة بالكائنات تلقائياً عند فك الترميز، فإن السجل يتم تحليله بنجاح دون الحاجة لمعالجة خاصة أو حذف استباقي قد يخل بالحساب البايتي للمصفوفة.
تحتاج الإزاحات إلى عدّ البايتات إذا كان المصدر الذي ستعود إليه مقروءاً بالبايتات. عدد محارف نص Unicode لا يساوي بالضرورة طول تمثيله في UTF-8. يحسب القارئ len(line) قبل تحويل السطر إلى كائن Python، فيبقى الحساب متعلقاً بالمدخل الثنائي نفسه. كانت اختبارات القارئ الأولى تستعمل أسماء ASCII في مواضعها العددية؛ أما اختبار المجمّع الإضافي أدناه فيستعمل معرفاً عربياً ويقسمه إلى قطع من بايت واحد، ثم يقارن العداد بالطول البايتي الأصلي. كلاهما فحص محلي داخل الذاكرة. لا تقرأ هذه الأرقام باعتبارها مواضع مطلقة على قرص أو مؤشرات صالحة بعد تغيير الملف الذي أُخذت منه البيانات.
أما الرموز الفاصلة غير المعتمدة، مثل رمز الجدولة العمودية \x0b المختبر في b'{"id":\x0b"a"}'، فإن القارئ لا يعتبرها فواصل أسطر على الإطلاق لأن التجزئة محصورة صراحة في b'\n'. تظل هذه الرموز محتجزة بالكامل ضمن حقل held_tail ككتلة واحدة دون تجزئة. هذا السلوك يوضح أن الاختبار لم يقم بأي تحويل لصيغ السطور أو تسوية ليونيكود، بل التزم حرفياً بالقاعدة الثنائية الصارمة المحددة لفصل السجلات.
تفصل عملية bytes.split عند فاصل البايتات المحدد، ويستعمل المثال LF صراحة لحفظ الذيل من دون فك UTF-8 مبكراً. Python3.12 bytes operations
اربط القارئ بمستهلك دون اختراع التزام دائم
يجب على المطور الذي يدمج هذا القارئ في نظامه إدراك أن عداد committed_bytes لا يعبر عن التزام دائم بحفظ البيانات على القرص الصلب، ولا يقدم أي ضمان لمعالجة السجل داخل قاعدة البيانات. هذا العداد ليس سوى مؤشر محلي لطول البادئة الثنائية التي اجتازت شروط القراءة بنجاح داخل مصفوفة الذاكرة المعطاة. بناء عليه، فإن المستهلك الخارجي هو المسؤول الحصري عن إدارة نقاط الحفظ وتأكيد اكتمال المهام المرتبطة بالسجلات المقروءة.
يمكن أن يختار المستدعي الاحتفاظ بالمخزن الخام وإعادة التحليل، أو الاحتفاظ بالذيل ودمجه بالقطعة الجديدة. إذا اختار الأسلوب الثاني، فليمرر held_tail + new_chunk دون أن يضيف إليه بادئة سبق قبولها مرة أخرى. سيطبق المساعد الجديد أدناه هذا الأسلوب داخل استدعاء واحد، لكن لا يلزم من ذلك أن تكون ذاكرته محدودة: فهو يحتفظ بكل السجلات المقبولة في قائمة، وقد يكبر الذيل إذا لم يصل LF. اختر حدود الحجم وطريقة تسليم النتائج بحسب حاجة مشروعك واختبرها إن كانت مطلوبة. لم يُجر هنا قياس للاستهلاك أو مقارنة أداء بين الاستراتيجيتين، ولذلك لا يقال إن أحدهما حل مثبت لمصدر أكبر من الذاكرة.
عند استخدام أسلوب دمج الذيل بالدفعة الجديدة، تفقد الإزاحة المحلية committed_bytes المرجعية الكلية لموقع الملف الأصلي إذا كانت الدفعات تُقرأ بالتتابع من مصدر خارجي. يتعين على المستهلك في هذه الحالة إجراء ترجمة حسابية لموقع المؤشر عبر إضافة الإزاحة المقبولة محلياً إلى عداد كلي تراكمي يحتفظ به المستهلك بنفسه، مما يضمن التتبع الصحيح لمواضع الانطلاق في حال رغب في تسجيل مواضع المعالجة لأغراض التدقيق البرمجي.
يخلو هذا القارئ المحلي من آليات فحص تكرار المعرفات duplicate-ID أو إدارة نقاط الاستئناف الدائمة، وهي مهام تقع خارج نطاق الدالة المعزولة. إذا كُتب السجل نفسه مرتين متتاليتين في الملف، فسيقبلهما القارئ كسجلين منفصلين طالما استوفى كل منهما الشروط الهيكلية. تقع على عاتق طبقة المستهلك مهمة التحقق من تفرد المعرفات والتعامل مع حالات إعادة التشغيل لضمان عدم تكرار معالجة السجلات المستهلكة سابقاً.
اقرأ الفحوص الاثني عشر وما لم تختبره
جرى التحقق من سلوك هذا القارئ عبر اثنتي عشرة طريقة اختبارية منفصلة داخل بيئة unittest محلية باستخدام بيانات اصطناعية محملة في الذاكرة تحت بيئة بايثون 3.12.3. الاختبار الأول test_broken_reader_raises_on_tail يؤكد فشل القارئ الساذج عند مواجهة ذيل مبتور، بينما يثبت test_hold_incomplete_tail احتجاز الذيل وإرجاع السجل المكتمل الوحيد مع موضع 11 بايت، ويتحقق test_valid_unterminated_json_still_held من احتجاز كائن JSON سليم لم يتبعه فاصل سطري.
تغطي الاختبارات التالية حالات الرفض الصارم للسجلات المكتملة المعطوبة: إذ يتحقق test_corrupt_complete_middle_rejected من إطلاق RecordError وتحديد السطر 2 والموضع 11، ويفحص test_invalid_utf8_complete_rejected رفض بايتات الترميز الفاسدة، ويختبر test_blank_line_rejected رفض الأسطر الفارغة، ويرفض test_nonobject_rejected مصفوفات JSON. كما يختبر test_string_input_rejected رفض النصوص، ويفحص test_empty حالة الدخل الفارغ، وtest_crlf_counted_as_bytes لاحتساب فاصل ويندوز، وtest_appending_tail_then_newline لإلحاق اللاحقة بالذيل، وtest_non_lf_separator_retained_in_tail لاحتجاز الفواصل الرأسية.
من الضروري التمييز بدقة بين هذه الفحوص الاثني عشر المنفذة محلياً في الذاكرة وبين المتطلبات التشغيلية الأوسع التي لم تخضع للاختبار في هذه الشيفرة. لم يُجرَ أي اختبار لقطع الملفات على القرص، أو محاكاة تعطل نظام التشغيل المفاجئ، أو تنافس عمليات الكتابة المتزامنة، أو قياس استهلاك الذاكرة عند تدفق كميات بيانات ضخمة تفوق سعة الذاكرة المتاحة. الدالة تفترض مسبقاً أن كامل كتلة الدخل موجودة سلفاً في الذاكرة ككائن واحد.
لم تفحص مجموعة القارئ الأولى ذات الاثنتي عشرة طريقة انقسام محرف UTF-8 عبر قطع متعددة؛ كان دخلها كتلة bytes جاهزة لكل استدعاء. يضيف المجمّع في القسم التالي ثماني طرق أخرى، ومنها تمرير السجل العربي بايتاً بايتاً. يوسع ذلك الدليل المحلي إلى طريقة تجميع محددة دون اختبار شبكة أو مزود أو كتابة متزامنة. احتفظ بتمييز المجموعتين عند قراءة نتائج التشغيل: القارئ يفحص السجل الذي يملك حد LF، والمجمّع يدير بقاء الذيل حتى وصول ذلك الحد. لا تكفي حالة النص العربي وحدها لإثبات سلامة كل بروتوكول تدفق أو دعم استئناف دائم، لكنها حالة انحدار قابلة لإعادة التنفيذ للامتداد المعروض.
ضع عقداً للكاتب والتزامن قبل قراءة ملف حي
عند الانتقال من قراءة مصفوفات الذاكرة إلى قراءة ملف سجل حي تتم الكتابة عليه بالتزامن بواسطة عمليات أخرى، تبرز الحاجة الماسة إلى صياغة عقد تنسيقي صريح بين الكاتب والقارئ. كتابة سجل مجزأ على القرص ليست بالضرورة خطأ دائم؛ فقد تكون العملية الكاتبة بصدد إفراغ دفعة جزئية عبر وسيط تخزين مؤقت. ومع ذلك، فإن مجرد وجود بايت السطر الجديد LF لا يوفر ضمانة ذرية تلقائية باكتمال كتابة السجل على الوسائط المادية ما لم تُستخدم آليات تزامن صلبة.
لتفادي مشكلات تداخل البايتات عند تعدد مصادر التوليد، يُوصى باعتماد نموذج الكاتب المنفرد single writer أو تنظيم الوصول عبر أقفال الملفات المشتركة، أو توجيه السجلات عبر وسيط رسائل وسطي بدلاً من الكتابة العشوائية المباشرة في ملف واحد. إضافة إلى ذلك، يجب على نظام المراقبة التمييز بدقة بين ذيل متوقف ينتظر اكتمال دفقته الطبيعية، وبين تعرض الملف لعملية استبدال شاملة أو اقتطاع مفاجئ truncation يقلل حجم الملف عن الموضع المسجل، وهو أمر يستوجب رصداً مستقلاً لمعرفات الملفات وأحجامها.
تظل المقترحات الخاصة بإضافة عمليات فحص اتساق إضافية، مثل رفض المفاتيح المكررة في JSON عبر تزويد loads بمعالج مخصص object_pairs_hook، أو فرض قيود تفحص تجريد المسافات البيضاء في المعرفات النصية strip، مجرد توصيات برمجية مقترحة لم يتم تنفيذها أو اختبارها داخل الكود المعتمد حالياً. إذا تطلبت متطلبات المشروع منع المعرفات المكونة من مسافات فقط أو التحقق من صحة حقول إضافية كأبعاد الصور أو تواريخ المعالجة، فيتعين دمج هذه القيود صراحة ضمن كتلة التحقق واختبارها باختبارات مستقلة.
تعتمد الخطوة التالية لقبول هذا النموذج في خطوط الإنتاج على تحديد متطلبات المستهلك بوضوح: هل سيعتمد سياسة إعادة المحاولة عند الذيل العالق لفترة تتجاوز حداً زمنياً معلوماً، أم سيُطلق إنذاراً بتلف البيانات؟ اتخاذ هذه القرارات التشغيلية، بالتوازي مع تصميم آليات التأكيد النهائي خارج نطاق القارئ، يضمن معالجة متزنة تجمع بين الحزم في رفض البيانات الفاسدة والمرونة في استيعاب تدفق السجلات الحية دون توقف غير مبرر.
اجمع قطع البايتات بمساعد مستقل واختبر انقسام النص العربي
أضيف إلى المشروع مساعد collect_chunks لمعالجة تسلسل من قطع البايتات داخل الذاكرة، بدلاً من ترك جمع الذيل مجرد اقتراح. يستورد هذا المساعد read_complete_records من الملف السابق، ويحتفظ بثلاث قيم أثناء الاستدعاء: قائمة records، وذيل tail، وعدّاد consumed. في كل دورة يفحص أن القطعة من نوع bytes، ثم يستدعي القارئ على tail + chunk. يضيف السجلات المقبولة إلى قائمته ويجمع طول البادئة المقبولة في العداد، ويستبدل الذيل بالذيل الذي أعاده القارئ. هذه خطوات منفذة في الكود الجديد، وليست آلية قراءة ملف أو استرجاع مهمة من مزود. عليك توفير القطع بالترتيب الذي تريد تفسيره، دون إعادة إرسال بادئة سبق تقديمها.
تختبر إحدى الطرق الجديدة جميع مواضع القطع إلى جزأين في سلسلة تحتوي السجلين a وb. لكل موضع، تقدم الاختبار البادئة ثم اللاحقة وتؤكد أن الناتج يحوي السجلين نفسيهما؛ تجمع حالات subTest تحت طريقة واحدة، فلا تخلط عدد المواضع بعدد الطرق. وفي طريقة أخرى، يُنشأ سجل اصطناعي بالمعرف العربي صورة وترميز UTF-8 ثم يمرر بايتاً واحداً في كل قطعة. يؤكد الاختبار المعرف المعاد ومساواة committed_bytes لطول سلسلة البايتات الأصلية. هذا دليل على التعامل مع التجزؤ المحدد في الذاكرة، ولا يحوله إلى اختبار لشبكة أو ملف حي أو أداء تحت ضغط.
تعطي حالة احتجاز الذيل مثالاً يمكن تتبعه دون قراءة محارف مبتورة: القطعة الأولى هي b'{"id":'، والثانية تكمل السجل a ثم تبدأ سجلاً آخر لا يكتمل. تعيد collect_chunks السجل a مع committed_bytes=11 والذيل b'{"id":'. يحسب المساعد العداد عبر البادئات المقبولة، بينما يبقى الذيل الحالي خارج هذا المجموع. إذا كانت كل القطع متتابعة من نقطة البداية نفسها، يمثل العداد مجموع تلك البايتات المقبولة في هذا الاستدعاء. لا يحفظ المساعد هذا الرقم على قرص، ولا يعرف إزاحة ملف بدأ المستدعي قراءته من منتصفه؛ يحتاج ربط الرقم بمصدر خارجي إلى سياق يملكه المستدعي.
توجد ثماني طرق اختبار جديدة للمجمّع إلى جانب الطرق الاثنتي عشرة للقارئ، وأصبح سجل التشغيل المشترك يضم عشرين طريقة. تشمل الطرق الجديدة مواضع القطع، والنص العربي، وبقاء الذيل، وفساد سجل في قطعة لاحقة، والدخل الفارغ، ورفض قطعة ليست bytes، واحتجاز JSON صالح بلا LF، وبقاء معرفين مكررين كسجلين. الطريقة الأخيرة توثق أن الجمع لا يزيل التكرار؛ فلا تستعمله آلية لإثبات تنفيذ المهام مرة واحدة. كما أن تمرير مقطع فاسد مكتمل يرفع RecordError ولا يعيد قائمة جزئية، حتى إن كانت قائمة داخلية قد جمعت سجلات من قطعة سابقة في الاستدعاء نفسه.
يظل موضع الخطأ في رسالة RecordError محلياً للمخزن الذي تلقاه القارئ في تلك الدورة، أي الذيل مضافاً إليه القطعة الجديدة. لا يحوّله المساعد تلقائياً إلى رقم سطر أو إزاحة كلية للملف. إذا احتجت تقريراً كلياً، فأضف سياق البداية وعدد السطور المقبولة إلى تصميم الأخطاء واختبره؛ لا تكتف بإعادة تسمية الرقم المحلي. كذلك يحتفظ المساعد بجميع السجلات المقبولة في قائمة حتى ينتهي الاستدعاء. هو ليس مولداً يسلّم سجلاً بعد سجل، ولا يفرض حداً لذاكرة الذيل أو القائمة، ولا ينفذ ضغطاً عكسياً على مصدر البيانات. هذه حدود مهمة قبل اختيار طريقة توصيل مصدر كبير به.
لإعادة التجربة احتفظ بملفي jsonl_tail.py وchunk_collector.py في المجلد نفسه وبملفي الاختبارات، وشغّل اكتشاف unittest بنمط test_*.py. حُفظ المصدر وبصمته ونتيجة التشغيل المحلية، مع فصل الفحوص الأولى عن الامتداد الجديد. إذا أردت تحويل هذا المساعد إلى قارئ ملف مستمر، فابدأ بعقد إدخال يحدد ترتيب القطع ومصدرها وكيفية اكتشاف استبدال الملف أو تقصيره. ثم اختر سياسة حفظ وتأكيد منفصلة للمستهلك. لا تضف إلى هذا الاستدعاء افتراضاً بأن كل ما قبله ثبت على القرص أو نُفذ بنجاح، لأن النجاح هنا يعني فقط أن البايتات التي وصلت اجتازت قواعد القارئ والمجمّع المختبرة.
أُعد المقال بمساعدة أدوات ذكاء اصطناعي ومراجعات تحريرية آلية. اختُبر المثال الأصلي محلياً ببيانات اصطناعية، دون تشغيل خدمة صور أو فيديو أو قياس نظام إنتاجي.
chunk_collector.py
from jsonl_tail import read_complete_records
def collect_chunks(chunks):
records, tail, consumed = [], b'', 0
for chunk in chunks:
if not isinstance(chunk, bytes):
raise TypeError('Expected byte chunks')
result = read_complete_records(tail + chunk)
records.extend(result['records'])
consumed += result['committed_bytes']
tail = result['held_tail']
return {'records': records, 'committed_bytes': consumed, 'held_tail': tail}
نطاق التحقق المحلي: Eight new chunk-collector methods plus twelve original reader methods,20total. In-memory synthetic byte chunks, including an Arabic UTF8 record split into individual bytes. No file/network access, durable checkpoint, streaming output, backpressure, memory bound or deduplication. Records are accumulated until the final return; a later error raises and returns no partial result. Error location belongs to the current tail+chunk buffer, not automatically to a global file position.؛ البيئة: Python3.12.3 on Windows
التعليقات
كن أول من يعلّق على هذا المقال.