Update helpers/utils.py

helpers/utils.py

@@ -7,12 +7,16 @@ from helpers.cleaner import clean_text
 ARABIC_INDIC_DIGITS = str.maketrans("٠١٢٣٤٥٦٧٨٩", "0123456789")
 
 def normalize_digits(s: str) -> str:
+    """تحويل الأرقام الهندية إلى عربية"""
+    if not isinstance(s, str):
+        return ""
     return s.translate(ARABIC_INDIC_DIGITS)
 
 # ---------------------------------------
 # دالة تنظيف النص + تحويل الأرقام
 # ---------------------------------------
 def clean_text_block(text: str) -> str:
+    """تنظيف النص وتحويل الأرقام للهندية → عربية"""
     if not isinstance(text, str):
         return ""
     return clean_text(normalize_digits(text.strip()))
@@ -21,20 +25,28 @@ def clean_text_block(text: str) -> str:
 # أنماط المواد والأقسام
 # ---------------------------------------
 
+# نمط المادة: يدعم "مادة" و"ماده" و"المادة" و"المادّة" مع رقم وربما "مكرر"
 ARTICLE_PATTERN = re.compile(
     r"^\s*(?:ال?ماد[ةه])\s*[\(]?\s*([0-9٠-٩]+(?:\s*مكرر)?)\s*[\)]?\s*(.*)$",
     re.IGNORECASE
 )
 
+# نمط القسم: الباب أو الفصل أو القسم
 SECTION_PATTERN = re.compile(
     r"^\s*(الباب|الفصل|القسم)\s+([^\n]+)",
     re.IGNORECASE
 )
 
 # ---------------------------------------
-# دالة واحدة لتحديد نوع السطر
+# دالة تحديد نوع السطر
 # ---------------------------------------
 def detect_line_type(text: str) -> str:
+    """
+    تحديد نوع السطر:
+    - 'section' → بداية قسم (باب/فصل/قسم)
+    - 'article' → بداية مادة
+    - 'text' → نص عادي
+    """
     if not isinstance(text, str) or not text.strip():
         return "text"
 
@@ -47,9 +59,15 @@ def detect_line_type(text: str) -> str:
     else:
         return "text"
 
+# ---------------------------------------
+# استخراج رقم المادة كـ int
+# ---------------------------------------
 def extract_article_number(text: str) -> int | None:
     """
-    استخراج رقم المادة كـ int، حتى لو كانت مكتوبة بصيغة "مكرر".
+    استخراج رقم المادة من النص:
+    - يحول الرقم للهندية → عربية
+    - يتجاهل كلمة "مكرر"
+    - يرجع int أو None
     """
     if not isinstance(text, str):
         return None
@@ -58,7 +76,7 @@ def extract_article_number(text: str) -> int | None:
     m = ARTICLE_PATTERN.match(text_norm)
     if m:
         number_str = m.group(1)
-        # إزالة أي كلمة "مكرر" و المسافات
+        # إزالة أي كلمة "مكرر" والمسافات
         number_only = re.match(r'(\d+)', number_str)
         if number_only:
             return int(number_only.group(1))