Create output_clipper.py

helpers/output_clipper.py

@@ -0,0 +1,290 @@
+from typing import List, Dict, Optional, Tuple, Union
+
+class OutputClipper:
+    """
+    كلاس للتحكم في قص وتصفية المخرجات النصية
+    """
+    
+    def __init__(self):
+        pass
+    
+    def clip_by_ranges(
+        self, 
+        data: List[Dict[str, str]], 
+        ranges: List[Tuple[int, int]]
+    ) -> List[Dict[str, str]]:
+        """
+        قص البيانات حسب النطاقات المحددة
+        
+        Args:
+            data: البيانات الأصلية [{'text': 'content'}, ...]
+            ranges: النطاقات [(start, end), (start, end), ...]
+        
+        Returns:
+            البيانات المقصوصة حسب النطاقات
+        """
+        if not ranges or not data:
+            return data
+        
+        total_items = len(data)
+        clipped_data = []
+        
+        for start, end in ranges:
+            # تنظيف النطاقات
+            start = max(0, start)
+            end = min(total_items, end)
+            
+            # تجاهل النطاقات غير الصحيحة
+            if start >= end:
+                continue
+            
+            # إضافة العناصر من النطاق المحدد
+            range_items = data[start:end]
+            clipped_data.extend(range_items)
+        
+        return clipped_data
+    
+    def clip_by_count(
+        self, 
+        data: List[Dict[str, str]], 
+        start: int = 0, 
+        count: Optional[int] = None
+    ) -> List[Dict[str, str]]:
+        """
+        قص البيانات حسب نقطة البداية وعدد العناصر
+        
+        Args:
+            data: البيانات الأصلية
+            start: نقطة البداية (افتراضي 0)
+            count: عدد العناصر المطلوبة (None للكل)
+        
+        Returns:
+            البيانات المقصوصة
+        """
+        if not data:
+            return data
+        
+        start = max(0, start)
+        
+        if count is None:
+            return data[start:]
+        
+        count = max(0, count)
+        end = start + count
+        
+        return data[start:end]
+    
+    def clip_by_text_length(
+        self, 
+        data: List[Dict[str, str]], 
+        min_length: int = 0, 
+        max_length: Optional[int] = None
+    ) -> List[Dict[str, str]]:
+        """
+        قص البيانات حسب طول النص
+        
+        Args:
+            data: البيانات الأصلية
+            min_length: الحد الأدنى لطول النص
+            max_length: الحد الأقصى لطول النص (None بلا حد أقصى)
+        
+        Returns:
+            البيانات المفلترة حسب طول النص
+        """
+        if not data:
+            return data
+        
+        filtered_data = []
+        
+        for item in data:
+            text_length = len(item['text'])
+            
+            # فحص الحد الأدنى
+            if text_length < min_length:
+                continue
+            
+            # فحص الحد الأقصى
+            if max_length is not None and text_length > max_length:
+                continue
+            
+            filtered_data.append(item)
+        
+        return filtered_data
+    
+    def clip_by_keywords(
+        self, 
+        data: List[Dict[str, str]], 
+        include_keywords: Optional[List[str]] = None,
+        exclude_keywords: Optional[List[str]] = None,
+        case_sensitive: bool = False
+    ) -> List[Dict[str, str]]:
+        """
+        قص البيانات حسب الكلمات المفتاحية
+        
+        Args:
+            data: البيانات الأصلية
+            include_keywords: كلمات يجب تضمينها
+            exclude_keywords: كلمات يجب استبعادها
+            case_sensitive: حساسية الأحرف الكبيرة والصغيرة
+        
+        Returns:
+            البيانات المفلترة حسب الكلمات المفتاحية
+        """
+        if not data:
+            return data
+        
+        filtered_data = []
+        
+        for item in data:
+            text = item['text']
+            
+            if not case_sensitive:
+                text_lower = text.lower()
+            
+            # فحص كلمات التضمين
+            if include_keywords:
+                found_include = False
+                for keyword in include_keywords:
+                    check_keyword = keyword.lower() if not case_sensitive else keyword
+                    check_text = text_lower if not case_sensitive else text
+                    
+                    if check_keyword in check_text:
+                        found_include = True
+                        break
+                
+                if not found_include:
+                    continue
+            
+            # فحص كلمات الاستبعاد
+            if exclude_keywords:
+                found_exclude = False
+                for keyword in exclude_keywords:
+                    check_keyword = keyword.lower() if not case_sensitive else keyword
+                    check_text = text_lower if not case_sensitive else text
+                    
+                    if check_keyword in check_text:
+                        found_exclude = True
+                        break
+                
+                if found_exclude:
+                    continue
+            
+            filtered_data.append(item)
+        
+        return filtered_data
+    
+    def remove_duplicates(
+        self, 
+        data: List[Dict[str, str]], 
+        preserve_order: bool = True
+    ) -> List[Dict[str, str]]:
+        """
+        إزالة التكرارات من البيانات
+        
+        Args:
+            data: البيانات الأصلية
+            preserve_order: الحفاظ على الترتيب الأصلي
+        
+        Returns:
+            البيانات بدون تكرارات
+        """
+        if not data:
+            return data
+        
+        seen = set()
+        unique_data = []
+        
+        for item in data:
+            text_content = item['text']
+            if text_content not in seen:
+                seen.add(text_content)
+                unique_data.append(item)
+        
+        return unique_data
+    
+    def combine_clips(
+        self, 
+        data: List[Dict[str, str]], 
+        ranges: Optional[List[Tuple[int, int]]] = None,
+        min_length: Optional[int] = None,
+        max_length: Optional[int] = None,
+        include_keywords: Optional[List[str]] = None,
+        exclude_keywords: Optional[List[str]] = None,
+        remove_duplicates: bool = True,
+        max_results: Optional[int] = None
+    ) -> List[Dict[str, str]]:
+        """
+        تطبيق عدة فلاتر معاً
+        
+        Args:
+            data: البيانات الأصلية
+            ranges: النطاقات
+            min_length: الحد الأدنى لطول النص
+            max_length: الحد الأقصى لطول النص
+            include_keywords: كلمات للتضمين
+            exclude_keywords: كلمات للاستبعاد
+            remove_duplicates: إزالة التكرارات
+            max_results: الحد الأقصى للنتائج
+        
+        Returns:
+            البيانات المفلترة نهائياً
+        """
+        result = data.copy()
+        
+        # تطبيق فلتر النطاقات
+        if ranges:
+            result = self.clip_by_ranges(result, ranges)
+        
+        # تطبيق فلتر طول النص
+        if min_length is not None or max_length is not None:
+            result = self.clip_by_text_length(
+                result, 
+                min_length or 0, 
+                max_length
+            )
+        
+        # تطبيق فلتر الكلمات المفتاحية
+        if include_keywords or exclude_keywords:
+            result = self.clip_by_keywords(
+                result, 
+                include_keywords, 
+                exclude_keywords
+            )
+        
+        # إزالة التكرارات
+        if remove_duplicates:
+            result = self.remove_duplicates(result)
+        
+        # تحديد عدد النتائج النهائي
+        if max_results is not None and max_results > 0:
+            result = result[:max_results]
+        
+        return result
+
+# دوال مستقلة للاستخدام السريع
+def clip_by_ranges(data: List[Dict[str, str]], ranges: List[Tuple[int, int]]) -> List[Dict[str, str]]:
+    """دالة مستقلة لقص البيانات حسب النطاقات"""
+    clipper = OutputClipper()
+    return clipper.clip_by_ranges(data, ranges)
+
+def clip_by_count(data: List[Dict[str, str]], start: int = 0, count: Optional[int] = None) -> List[Dict[str, str]]:
+    """دالة مستقلة لقص البيانات حسب العدد"""
+    clipper = OutputClipper()
+    return clipper.clip_by_count(data, start, count)
+
+def clip_by_keywords(
+    data: List[Dict[str, str]], 
+    include: Optional[List[str]] = None,
+    exclude: Optional[List[str]] = None
+) -> List[Dict[str, str]]:
+    """دالة مستقلة لفلترة الكلمات المفتاحية"""
+    clipper = OutputClipper()
+    return clipper.clip_by_keywords(data, include, exclude)
+
+def advanced_clip(
+    data: List[Dict[str, str]], 
+    **kwargs
+) -> List[Dict[str, str]]:
+    """دالة مستقلة للفلترة المتقدمة"""
+    clipper = OutputClipper()
+    return clipper.combine_clips(data, **kwargs)