html2text لا يتجاوز 0.2 ميغابايت ومكوّن من حزمة واحدة. كما أنه مرخّص تحت GPL-3.0.

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

كما أنه صادر بترخيص GPL-3.0-or-later، وهي الخاصية الوحيدة في هذه المقارنة التي لا تظهر في أي اختبار معياري، وقد تكون كافية وحدها لاستبعاد المكتبة بالكامل.

ما هو html2text

html2text هي مكتبة Python تحوّل HTML إلى نص قريب من Markdown. تعود جذورها إلى النسخة الأصلية التي أنشأها Aaron Swartz، أما النسخة الحالية المدعومة فتقف عند 2025.4.15 — إصدار مؤرخ من أبريل 2025، مع 2,168 نجمة على GitHub، و95 مشكلة مفتوحة، وآخر تحديث في أكتوبر 2025.

المرجع الرسمي: المستودع الرسمي لـ html2text.

import html2text
h = html2text.HTML2Text()
h.body_width = 0          # انظر أدناه؛ الإعداد الافتراضي قد يفاجئك
md = h.handle(html)

الأمر pip install html2text يجلب حزمة واحدة فقط وبحجم 0.2 ميغابايت، مع وقت استيراد بارد يبلغ 0.077 ثانية. ولا توجد أي تبعيات. وفي صورة حاوية أو طبقة Lambda، فهذا فارق ملموس مقارنةً بـ markdownify بحجم 1.8 ميغابايت وturndown بحجم 8.8 ميغابايت.

الإعداد الافتراضي الذي يغيّر كل رقم

القيمة الافتراضية لـ body_width هي 78. أي أن html2text يعيد لفّ كل سطر في الناتج عند 78 حرفًا ما لم توقف ذلك يدويًا.

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

أضبطت body_width = 0 لكل ما يلي، وأذكر ذلك صراحة بدلًا من إخفائه: مع تشغيل اللفّ، كانت كل أعداد الأحرف والرموز في هذا المقال ستختلف. إذا كنت تجري المقارنة بنفسك، فهذا هو الإعداد الذي سيجعل أرقامك غير قابلة للمقارنة من دون أن تلاحظ.

طريقة القياس

شغّلت html2text على مجموعة تحويل مؤلفة من أربع صفحات ومسمّاة، وهي نفسها المستخدمة في مقارنة markitdown، مع سلاسل تحقق مسجّلة مسبقًا — وهي سلاسل نصية محددة داخل المتن يجب أن تبقى، إلى جانب سلاسل نصية قياسية وجودها يدل على انتقال عناصر الصفحة كما هي. نفس الملفات الأربعة، ونفس المؤشرات، ومقيّم واحد عبر المحولات الأربع. بقاء المؤشر يقيس فقط وجود السلسلة المسجّلة، لا صحة البنية؛ ولهذا فصلتُ بين أعمدة الجداول والروابط.

fourway-scores.json. أربع عينات، مع احتساب الرموز عبر o200k_base.

أصغر ناتج بين الأربعة عند 76,452 حرفًا، ومتقارب عمليًا في عدد الرموز مع markdownify وmarkitdown — 21,176 مقابل 21,062 و21,336، بفارق 1.3% لا أعدّه فرقًا جوهريًا.

32 صفًا في الجداول مقابل 36 لدى markdownify وmarkitdown في مجموعة الصفحات الأربع. ويظهر فارق الأربعة صفوف في عينة ويكيبيديا غير المنتظمة، لا في فرق تنسيق الشرطة العمودية الخارجية الذي سيأتي بعد قليل.

أقل عدد من الروابط: 545، مقابل 598 إلى 611 لدى الآخرين. هذه نقطة تستحق التحقق في صفحاتك إن كان الحفاظ على الروابط مهمًا؛ فهي العمود الوحيد الذي يقع فيه html2text بوضوح دون المجموعة الأخرى.

الجداول التي لم يرَها regex الخاص بي

هذه القصة تستحق السرد لأنني كدت أنشر نتيجة خاطئة بشأنها.

كان أول عدّاد لصفوف الجداول عندي يتطلب وجود خطوط عمودية في البداية والنهاية — ^\|.*\|$. ووفق هذا الشرط، حصل html2text على صف جدول واحد فقط عبر خمسة ملفات: مجموعة الصفحات الأربع إضافة إلى عينة منفصلة صناعية لجدول معقد. لكن هذا العداد كان يقيس أسلوبًا واحدًا من Markdown، لا الجداول نفسها.

هو يفعل ذلك. ويُخرجها بهذا الشكل:

Team Name  |  Year  |  Wins  |  Losses  |  Win %
---|---|---|---|---
Boston Bruins  |  1990  |  44  |  24  |  0.55

من دون خطوط عمودية خارجية. هذا تنسيق شائع لجداول Markdown، لكن الإطار الاختباري لم يتحقق من توافقه عبر عارضات Markdown المختلفة. ولهذا فهو غير مرئي لعدّاد regex يتوقع أسلوب الخطوط العمودية الخارجية. وعندما أعدتُ كتابة العداد ليلتقط سلسلة من الأسطر التي تحتوي على خطوط عمودية مع سطر فاصل بداخلها، ارتفع html2text من صف واحد إلى 32 صفًا في مجموعة الصفحات الأربع و91 صفًا عبر الملفات الخمسة كلها.

إذن الخلاصة ليست أن html2text لا يدعم الجداول. بل إن محولين اثنين من هذه الأربعة يخرجان الجداول مع خطوط عمودية خارجية، وواحد لا يفعل ذلك، وهذا مهم إذا كنت ستعالج Markdown لاحقًا بأنماط مطابقة خاصة بك. هذه معلومة حقيقية كان يمكن أن أفوّتها لو وثقتُ برقمـي الأول.

ما الذي يحذفه، وأين يفقد الصفوف

هناك نتيجتان تدفعان في اتجاهين متعاكسين.

يحذف <script> و<style>. وبالاعتماد على مؤشرات لا تظهر إلا داخل هذه العناصر، فإن ناتج html2text عبر العينات يحتوي على صفر مؤشرات script وصفر مؤشرات style. بينما يحتوي ناتج turndown على 10 و84 — وفي عينة ويكيبيديا تحديدًا، ثمانية أسطر من إعدادات JavaScript المضمّنة في MediaWiki وCSS بقيمة 14,644 حرفًا (script-style-stripping.json). بالنسبة للناتج المرتبط بنموذج، كان هذا أكبر مصدر ملحوظ لنص زائد يمكن تجنّبه في تلك العينة. ولم يُقاس أي نموذج تكلفة لاحق.

ويفقد بعض صفوف الجداول في الصفحة الصعبة. وتُفهم مجموعة الصفحات الأربع كما يلي:

وتضيف العينة المنفصلة للجدول المعقد الصناعي 59 صفًا لـ html2text و62 صفًا لـ markdownify، ما يرفع الإجمالي عبر الملفات الخمسة إلى 91 و98. وهذه ليست جزءًا من المقارنة الأساسية ذات الصفحات الأربع. يتطابقان في الجدول النظيف الخاص بالإحصاءات الرياضية. أما في ويكيبيديا، حيث الجداول متداخلة وغير منتظمة، فيخرج html2text خمسة صفوف مقابل تسعة لدى markdownify.

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

الترخيص

المرجع الرسمي: html2text على PyPI.

تم التأكد من ذلك في ثلاثة أماكن: بيانات وصف PyPI، ومستودع GitHub، وملف METADATA الخاص بالحزمة المثبّتة، الذي يقرأ License-Expression: GPL-3.0-or-later.

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

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

لست محاميًا، وهذا ليس نصيحة قانونية — لكنه واقع موثق، لأنه الخاصية الأرجح أن تهمك، والأقل ظهورًا في جداول المقارنة.

الصيانة

آخر إصدار 2025.4.15، وآخر دفع إلى المستودع في أكتوبر 2025 — أي قبل الاختبار بنحو عشرة أشهر، مع 41 إصدارًا خلفه. ويتطلب requires_python >= 3.9، وقد تم تثبيته وتشغيله بنجاح على Python 3.14.2.

هذا هادئ أكثر من markdownify (آخر إصدار قبل ستة أسابيع من الاختبار) وturndown (قبل أربعة أشهر)، وأكثر نشاطًا بكثير من غياب النشاط. بالنسبة لمكتبة تحوّل HTML إلى نص — وهي مشكلة لا تتغير كثيرًا — فإن فجوة عشرة أشهر تبدو استقرارًا لا إهمالًا. والعدد الأكبر الذي يستحق الانتباه هو 95 مشكلة مفتوحة، ومن المفيد مراجعته بحثًا عمّا يشبه حالة استخدامك قبل الالتزام.

الذاكرة، وما الذي يفعله HTML المعطوب بها

يُقاس هنا سؤالان تشغيليان بشكل منفصل.

سياق اختبار الضغط الأوسع موجود في مقارنة الذاكرة وHTML المعطوب عبر عشرة مكتبات.

أقصى ذاكرة مقيمة، عبر /usr/bin/time -l، مع عملية جديدة لكل خلية — الحد الأدنى للاستيراد هو ما تستهلكه المكتبة وهي محمّلة وخاملة، أما الذروات فتشمل المستند نفسه.

memory-results.json. لا يمكن مقارنة أساسيات Python وNode مباشرةً مع بعضها؛ فالمفسّر موجود في كليهما.

html2text هو أخف إدخال هنا على كلا المحورين المقيسين. فحده الأدنى للاستيراد 18.7 ميغابايت وذروته 71.2 ميغابايت على عينة 10 ميغابايت، ما يعطي زيادة في RSS بمقدار 52.5 ميغابايت: (71.2 - 18.7) / 10 = 5.25× من حجم العينة. قارن ذلك بالصفوف المطلقة والتزايدية في الجدول، مع تذكّر التحفظ المذكور بشأن الأساسيات في Python وNode.

HTML المعطوب. اثنا عشر مستندًا، كل واحد منها يكسر شيئًا واحدًا فقط — وسوم غير مغلقة، أو عناصر داخلية متداخلة خطأ، أو سمات غير مقتبسة مع وجود مسافات، أو وسم إغلاق شارد، أو غياب <html> تمامًا، أو سمات مكررة، أو مستند مقطوع في منتصف الوسم، أو كيانات خاطئة، أو <script> غير مغلق، أو إعلان charset كاذب، أو تعليق يحتوي على ترميز، أو 600 مستوى من التداخل — إضافة إلى عينتي ضبط سليمتين وبأحجام مماثلة، لأن عبارة "لم يُرجع شيئًا" لا تقول شيئًا عن العطب إلا إذا كانت المكتبة صامتة أيضًا أمام مستند نظيف بالحجم نفسه.

لم يرفع html2text استثناءً في 0 من 14 ولم يُرجع فراغًا في 0، واستعاد 33/33 من العلامات الأساسية عبر العينات المعطوبة (malformed-results.json). ويُستثنى ملف واحد من هذا العدّ: وفق HTML5، كل ما يأتي بعد <script> غير المغلق يُعدّ محتوى script فعلًا، لذا فإن فقدانه هناك صحيح، بينما استعادته هو الانحراف.

الإيجابيات والسلبيات

لصالحه. حزمة واحدة، 0.2 ميغابايت، بلا تبعيات — وهي الأصغر بفارق كبير في هذه المقارنة. أصغر ناتج بين الأربعة، ومتقارب عمليًا في عدد الرموز مع markdownify وmarkitdown. يخرج بصيغة جداول pipe-table قابلة للتعرّف. يعمل على Python 3.14. وسلسلة تطويره طويلة ومستقرة.

ضده. GPL-3.0-or-later، بينما البدائل ليست كذلك. القيمة الافتراضية body_width=78، ما يفرض لفًّا للناتج ويغيّر القياسات أو الفروقات ما لم تُعطّله. أقل عدد من الروابط المحفوظة (545 مقابل 598–611). الجداول تستخدم أسلوبًا بلا خطوط عمودية خارجية، ما يكسر أنماط regex البسيطة في المعالجة اللاحقة. 95 مشكلة مفتوحة، وإيقاع الإصدارات أهدأ من markdownify.

من يجب أن يستخدمه، ومن لا يجب أن يستخدمه

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

اضبط body_width = 0 في السطر الأول، إلا إذا كنت تريد نصًا عاديًا ملفوفًا عمدًا.

تجاوزه إذا كنت توزّع برمجية وكان الترخيص المتساهل/المُلزِم مشكلة بالنسبة لك — markdownify يحمل MIT، ويعادلـه في عدد الرموز، ويطابق markitdown في الجداول مقابل 1.6 ميغابايت إضافية. وتجاوزه إذا كان الحفاظ على الروابط مهمًا، لأنه حفظ أقل عدد منها. وتجاوزه أيضًا إذا كانت أدواتك اللاحقة تفترض وجود خطوط عمودية خارجية في صفوف الجداول.

أين يناسب API مُدار

html2text يحوّل HTML الذي لديك أصلًا. لكنه لا يجلب الصفحات، ولا ينفذ JavaScript، ولا يتعامل مع طبقة anti-bot — ولا أيٌّ من المحولات الأربعة يفعل ذلك، ومع كثير من الأهداف الواقعية يكون ذلك هو الجزء الأصعب من المهمة.

وللاطلاع على نفس العينات عبر المحولات الخمسة كلها، راجع مقارنة HTML إلى Markdown عبر خمسة محولات.

أما خدمة الاسترجاع/العرض/الاستخراج المستضافة، بما في ذلك Thunderbit الخاصة بنا، فتعمل في طبقة مختلفة. ولم يخضع Thunderbit هنا للاختبار المعياري. الفاصل المهم هنا هو تحويل HTML المزوّد إليك مقابل خدمة تستخرج URL وتعالجه؛ وهذا المقال لا يقدم مقارنة مكافئة في الجودة أو الزمن أو التكلفة.

والصياغة العادلة هي: إذا كان HTML موجودًا لديك، وتريد Markdown، وكان GPL لا يسبب مشكلة لطريقة الشحن، فـ html2text مجاني وصغير بشكل لافت. أما إذا كنت تجلب الصفحات، أو تريد صفوفًا بدل النصوص، فهذه صفقة مختلفة.

وللإطار الأوسع، تتناول جولة حول واجهات برمجة تطبيقات الويب سكربنج الخيارات المستضافة، وتغطي مقالة المحولات مفتوحة المصدر الأساسية الخيارات ذاتية الاستضافة. أما تحويل HTML إلى Markdown في Python فهو الشرح العملي.

جرّب Thunderbit لاستخراج بيانات الويب

هل ينبغي استخدام html2text؟

هو خيار قوي عندما يكون حجم الأثر مهمًا، ويتم تعطيل اللفّ عمدًا، ويجتاز نموذج التوزيع مراجعة الترخيص.

كان عدد الرموز فيه ضمن 1.3% من markdownify وmarkitdown في مجموعة الصفحات الأربع. لكن هذا لا يعني تكافؤ الجودة الكلية: فقد احتفظ html2text بروابط أقل وصفوف أقل في عينة ويكيبيديا غير المنتظمة. وهناك تفصيلان تشغيليان مهمان فورًا: body_width = 0، وأسلوب الجداول بلا خطوط عمودية خارجية.

إذا استبعدته مراجعة GPL، فـ markdownify يحمل MIT، وكان هنا ذا حجم ناتج وعدد رموز متقاربين، واحتفظ بروابط أكثر وصفوف جداول غير منتظمة أكثر، مع استهلاك 1.6 ميغابايت إضافية على القرص في هذا السياق.

جرّب Thunderbit لاستخراج بيانات الويب Get Started Free

الأسئلة الشائعة

هل يحوّل html2text الجداول؟ نعم. كان عدّادي الأول يقول إنه ينتج صف جدول واحدًا عبر خمسة ملفات، لكن هذا كان خطأ — لأنه اشترط وجود خطوط عمودية في البداية والنهاية، بينما يخرج html2text Team Name | Year | Wins من دونها. هذا Markdown جدولي تقليدي بأسلوب pipe-table، رغم أن هذا الإطار لم يجرِ اختبار توافق عبر عارضات متعددة. وبعد تصحيح العدّاد، أنتج html2text 32 صفًا مقابل 36 لدى markdownify في مجموعة الصفحات الأربع، و91 مقابل 98 عند تضمين عينة الجدول المعقد المنفصلة.

ماذا يفعل body_width، ولماذا تغيّره؟ هو يلفّ الناتج عند 78 حرفًا افتراضيًا، وهو اختيار مناسب للنص المقروء في الطرفية، لكنه سيئ لأي استخدام آخر تقريبًا. فاللفّ يضيف أسطرًا جديدة داخل الجمل، ويقسم عناوين URL الطويلة عبر الأسطر، ويغيّر التقطيع إلى رموز. كل رقم في هذه المراجعة استُخدم فيه body_width = 0؛ ولو استُخدم الافتراضي، لتغيّرت كلها.

هل ترخيص GPL قيد حقيقي؟ يعتمد ذلك على نموذج الدمج والتوزيع الدقيق. الاستخدام الداخلي أو عبر الشبكة، وتوزيع البرمجيات، كلها سيناريوهات فحص مختلفة، لكن هذا المقال لا يحسم النتيجة القانونية لها. على الفرق التي تشحن برمجيات أن تعرض شروط GPL-3.0-or-later على مستشار قانوني؛ أما markdownify وturndown فهما MIT. وقد تأكد تعبير ترخيص html2text في بيانات PyPI وGitHub وملف METADATA الخاص بالحزمة المثبتة.

هل إصدار أبريل 2025 مشكلة؟ على الأرجح لا، بحد ذاته. تحويل HTML إلى نص مشكلة مستقرة، وقد تم تثبيت المكتبة وتشغيلها بنجاح على Python 3.14.2، وهناك 41 إصدارًا خلفها. أما 95 مشكلة مفتوحة فهي الرقم الذي كنت سأتفحصه فعليًا — راجعها بحثًا عمّا يشبه بياناتك قبل الالتزام، لأن المستودع الهادئ قد يعني أنك أنت من سيتولى إصلاحه.

ما الذي لم يُختبر هنا؟ أربع عينات تحويل وعينة منفصلة واحدة لجدول معقد ما تزال تمثل مجموعة صغيرة. لكن الاختبار شمل اثني عشر مستندًا صناعيًا معطوبًا وعينتي ضبط: لم يرفع html2text استثناءً في 0/14، ولم يُرجع فراغًا في 0/14، واستعاد كل المؤشرات الـ33 المقاسة. ولم يشمل صفحات حقيقية تالفة، أو أنماط عطب أوسع، أو القوائم المتداخلة، أو القوائم التعريفية، أو الحواشي، أو المعادلات. كما أن السطح الكامل للخيارات — ignore_links وignore_images وunicode_snob وsingle_line_break وغيرها — بقي على الإعدادات الافتراضية باستثناء body_width. كما لوحظت فجوة الروابط لكن لم تُشخّص، ولم يُختبر الرجوع بين Markdown مرة أخرى.