Create utils/helpers.py

utils/helpers.py

@@ -0,0 +1,326 @@
+import os
+import re
+import json
+import pandas as pd
+from typing import Dict, List, Any, Union, Tuple, Optional
+from datetime import datetime
+
+def format_currency(amount: float, currency: str = "ريال") -> str:
+    """
+    تنسيق المبالغ المالية
+    
+    المعاملات:
+    ----------
+    amount : float
+        المبلغ
+    currency : str, optional
+        العملة (افتراضي: "ريال")
+        
+    المخرجات:
+    --------
+    str
+        المبلغ بالتنسيق المناسب
+    """
+    if not amount and amount != 0:
+        return "غير محدد"
+    
+    # تنسيق الأرقام بالفواصل الآلاف
+    formatted = f"{amount:,.2f}".replace(".00", "")
+    
+    # ترتيب العملة حسب اللغة العربية (يمين)
+    return f"{formatted} {currency}"
+
+def format_percentage(value: float) -> str:
+    """
+    تنسيق النسب المئوية
+    
+    المعاملات:
+    ----------
+    value : float
+        القيمة
+        
+    المخرجات:
+    --------
+    str
+        النسبة بالتنسيق المناسب
+    """
+    if not value and value != 0:
+        return "غير محدد"
+    
+    return f"{value:.2f}%".replace(".00", "")
+
+def format_date(date_obj: Any) -> str:
+    """
+    تنسيق التواريخ
+    
+    المعاملات:
+    ----------
+    date_obj : Any
+        كائن التاريخ
+        
+    المخرجات:
+    --------
+    str
+        التاريخ بالتنسيق المناسب
+    """
+    if not date_obj:
+        return "غير محدد"
+    
+    # إذا كان التاريخ سلسلة نصية
+    if isinstance(date_obj, str):
+        try:
+            date_obj = datetime.strptime(date_obj, "%Y-%m-%d")
+        except ValueError:
+            try:
+                date_obj = datetime.strptime(date_obj, "%Y-%m-%d %H:%M:%S")
+            except ValueError:
+                return date_obj
+    
+    # تنسيق التاريخ بالطريقة العربية
+    month_names = [
+        "يناير", "فبراير", "مارس", "إبريل", "مايو", "يونيو", 
+        "يوليو", "أغسطس", "سبتمبر", "أكتوبر", "نوفمبر", "ديسمبر"
+    ]
+    
+    return f"{date_obj.day} {month_names[date_obj.month - 1]} {date_obj.year}"
+
+def extract_keywords(text: str, keywords: List[str], context_size: int = 50) -> List[Dict[str, str]]:
+    """
+    استخراج الكلمات المفتاحية من النص مع سياقها
+    
+    المعاملات:
+    ----------
+    text : str
+        النص المراد البحث فيه
+    keywords : List[str]
+        قائمة الكلمات المفتاحية
+    context_size : int, optional
+        حجم السياق بالأحرف قبل وبعد الكلمة (افتراضي: 50)
+        
+    المخرجات:
+    --------
+    List[Dict[str, str]]
+        قائمة بالكلمات المفتاحية وسياقها
+    """
+    results = []
+    
+    for keyword in keywords:
+        # البحث عن الكلمة المفتاحية في النص
+        pattern = re.compile(r'\\b' + re.escape(keyword) + r'\\b', re.IGNORECASE | re.MULTILINE)
+        matches = pattern.finditer(text)
+        
+        for match in matches:
+            start_idx = max(0, match.start() - context_size)
+            end_idx = min(len(text), match.end() + context_size)
+            
+            # استخراج السياق
+            context = text[start_idx:end_idx]
+            
+            # إضافة النتيجة
+            results.append({
+                "keyword": keyword,
+                "context": context,
+                "position": match.start()
+            })
+    
+    # ترتيب النتائج حسب الموقع في النص
+    results = sorted(results, key=lambda x: x["position"])
+    
+    return results
+
+def calculate_progress(current: float, total: float) -> Dict[str, Any]:
+    """
+    حساب نسبة الإنجاز
+    
+    المعاملات:
+    ----------
+    current : float
+        القيمة الحالية
+    total : float
+        القيمة الإجمالية
+        
+    المخرجات:
+    --------
+    Dict[str, Any]
+        معلومات التقدم
+    """
+    if total == 0:
+        return {
+            "percentage": 0,
+            "status": "لم يبدأ",
+            "color": "gray"
+        }
+    
+    percentage = min(100, (current / total) * 100)
+    
+    if percentage == 0:
+        status = "لم يبدأ"
+        color = "gray"
+    elif percentage < 25:
+        status = "بداية"
+        color = "red"
+    elif percentage < 50:
+        status = "قيد التنفيذ"
+        color = "orange"
+    elif percentage < 75:
+        status = "متقدم"
+        color = "blue"
+    elif percentage < 100:
+        status = "شبه مكتمل"
+        color = "teal"
+    else:
+        status = "مكتمل"
+        color = "green"
+    
+    return {
+        "percentage": round(percentage, 1),
+        "status": status,
+        "color": color
+    }
+
+def create_directory_structure(base_dir: str, structure: Dict[str, Any]) -> None:
+    """
+    إنشاء هيكل المجلدات
+    
+    المعاملات:
+    ----------
+    base_dir : str
+        المجلد الأساسي
+    structure : Dict[str, Any]
+        هيكل المجلدات
+    """
+    os.makedirs(base_dir, exist_ok=True)
+    
+    for key, value in structure.items():
+        path = os.path.join(base_dir, key)
+        
+        if isinstance(value, dict):
+            # إذا كانت القيمة قاموساً، استمر في إنشاء الهيكل الفرعي
+            create_directory_structure(path, value)
+        else:
+            # إنشاء المجلد
+            os.makedirs(path, exist_ok=True)
+            
+            # إذا كانت القيمة قائمة، إنشاء ملفات فارغة
+            if isinstance(value, list):
+                for file_name in value:
+                    file_path = os.path.join(path, file_name)
+                    if not os.path.exists(file_path):
+                        with open(file_path, 'w', encoding='utf-8') as f:
+                            # يمكن كتابة محتوى افتراضي هنا
+                            pass
+
+def export_to_excel(data: List[Dict[str, Any]], file_path: str, sheet_name: str = "Sheet1") -> bool:
+    """
+    تصدير البيانات إلى ملف Excel
+    
+    المعاملات:
+    ----------
+    data : List[Dict[str, Any]]
+        البيانات المراد تصديرها
+    file_path : str
+        مسار الملف
+    sheet_name : str, optional
+        اسم ورقة العمل (افتراضي: "Sheet1")
+        
+    المخرجات:
+    --------
+    bool
+        نجاح أو فشل العملية
+    """
+    try:
+        # تحويل البيانات إلى DataFrame
+        df = pd.DataFrame(data)
+        
+        # تصدير إلى Excel
+        df.to_excel(file_path, sheet_name=sheet_name, index=False)
+        
+        return True
+    except Exception as e:
+        print(f"Error exporting to Excel: {str(e)}")
+        return False
+
+def export_to_json(data: Any, file_path: str) -> bool:
+    """
+    تصدير البيانات إلى ملف JSON
+    
+    المعاملات:
+    ----------
+    data : Any
+        البيانات المراد تصديرها
+    file_path : str
+        مسار الملف
+        
+    المخرجات:
+    --------
+    bool
+        نجاح أو فشل العملية
+    """
+    try:
+        # إنشاء المجلد إذا لم يكن موجوداً
+        os.makedirs(os.path.dirname(file_path), exist_ok=True)
+        
+        # تصدير إلى JSON
+        with open(file_path, 'w', encoding='utf-8') as f:
+            json.dump(data, f, ensure_ascii=False, indent=4)
+        
+        return True
+    except Exception as e:
+        print(f"Error exporting to JSON: {str(e)}")
+        return False
+
+def validate_input(input_data: Dict[str, Any], validation_rules: Dict[str, Dict[str, Any]]) -> Dict[str, List[str]]:
+    """
+    التحقق من صحة البيانات المدخلة
+    
+    المعاملات:
+    ----------
+    input_data : Dict[str, Any]
+        البيانات المدخلة
+    validation_rules : Dict[str, Dict[str, Any]]
+        قواعد التحقق
+        
+    المخرجات:
+    --------
+    Dict[str, List[str]]
+        قائمة بالأخطاء لكل حقل
+    """
+    errors = {}
+    
+    for field, rules in validation_rules.items():
+        field_errors = []
+        value = input_data.get(field)
+        
+        # التحقق من الحقول المطلوبة
+        if rules.get("required", False) and (value is None or (isinstance(value, str) and value.strip() == "")):
+            field_errors.append("هذا الحقل مطلوب")
+        
+        # التحقق من النوع
+        if value is not None and "type" in rules:
+            expected_type = rules["type"]
+            if expected_type == "number" and not (isinstance(value, (int, float)) or (isinstance(value, str) and value.strip().replace(".", "", 1).isdigit())):
+                field_errors.append("يجب أن يكون هذا الحقل رقماً")
+            elif expected_type == "email" and not re.match(r'^[\w\.-]+@[\w\.-]+\.\w+$', str(value)):
+                field_errors.append("يرجى إدخال بريد إلكتروني صحيح")
+            elif expected_type == "date" and not re.match(r'^\d{4}-\d{2}-\d{2}$', str(value)):
+                field_errors.append("يرجى إدخال تاريخ صحيح (YYYY-MM-DD)")
+        
+        # التحقق من الحد الأدنى والأقصى
+        if value is not None and isinstance(value, (int, float)):
+            if "min" in rules and value < rules["min"]:
+                field_errors.append(f"يجب أن يكون هذا الحقل أكبر من أو يساوي {rules['min']}")
+            if "max" in rules and value > rules["max"]:
+                field_errors.append(f"يجب أن يكون هذا الحقل أصغر من أو يساوي {rules['max']}")
+        
+        # التحقق من طول النص
+        if value is not None and isinstance(value, str):
+            if "min_length" in rules and len(value) < rules["min_length"]:
+                field_errors.append(f"يجب أن يحتوي هذا الحقل على {rules['min_length']} أحرف على الأقل")
+            if "max_length" in rules and len(value) > rules["max_length"]:
+                field_errors.append(f"يجب أن يحتوي هذا الحقل على {rules['max_length']} أحرف كحد أقصى")
+        
+        # إضافة الأخطاء إذا وجدت
+        if field_errors:
+            errors[field] = field_errors
+    
+    return errors