devsamhan-arabic-text (Python)

مكتبة Python لتطبيع النص العربي — تشكيل، ألفات، همزات، بحث، فرز.

بدون تبعيات خارجية. متوافقة مع مواصفات devsamhan-arabic v1.0.1.

التثبيت

pip install devsamhan-arabic-text

أو محلياً:

pip install -e .

الاستخدام السريع

from devsamhan_arabic_text import (
    to_search_key, to_loose_search_key, to_display_key,
    to_slug, normalize_name, sort_arabic, compare_arabic,
    remove_tashkeel, normalize_alef, normalize_digits,
    is_arabic, arabic_ratio,
)

# مفتاح بحث للتخزين في قاعدة البيانات
to_search_key('مُحَمَّدٌ')       # → 'محمد'
to_search_key('فاطمة العلي')   # → 'فاطمة العلي'

# مفتاح متساهل: طبّقه على المفتاح المخزن المتساهل والاستعلام معاً
to_loose_search_key('فاطمة')   # → 'فاطمه'
to_loose_search_key('فاطمه')   # → 'فاطمه'
# ⚠️ لا تقارن هذا المفتاح بعمود to_search_key الصارم؛ استخدم عموداً متساهلاً.

# slug لـ URL
to_slug('مدينة الرياض')        # → 'مدينه-الرياض'

# ترتيب قائمة
sort_arabic(['يوسف', 'أحمد', 'محمد'])  # → ['أحمد', 'محمد', 'يوسف']

# تحويل الأرقام
normalize_digits('١٢٣', 'western')  # → '123'
normalize_digits('123', 'eastern')  # → '١٢٣'
normalize_digits('۱۲۳', 'eastern')  # → '١٢٣' (Persian is a source)

نمط قاعدة البيانات

خزّن النص الأصلي ومفتاحاً صارماً، وأضف عموداً متساهلاً اختيارياً. لا تغيّر search_key القائم.

ALTER TABLE students ADD COLUMN IF NOT EXISTS search_key_loose text;
UPDATE students SET search_key_loose = replace(search_key, 'ة', 'ه')
WHERE search_key IS NOT NULL AND search_key_loose IS NULL;

# حفظ: النص الأصلي + المفتاحان
cur.execute(
    "INSERT INTO students (name, search_key, search_key_loose) VALUES (%s, %s, %s)",
    (name, to_search_key(name), to_loose_search_key(name)),
)


def escape_like(value: str) -> str:
    return (
        value.replace("\\", "\\\\")
        .replace("%", "\\%")
        .replace("_", "\\_")
    )


# بحث متساهل حرفي: متساهل/متساهل — لا تستخدم search_key هنا
key = to_loose_search_key(query.strip())
if not key:
    rows = []
else:
    pattern = f"%{escape_like(key)}%"
    cur.execute(
        "SELECT id, name FROM students "
        "WHERE search_key_loose LIKE %s ESCAPE '\\'",
        (pattern,),
    )
    rows = cur.fetchall()

-- PostgreSQL: $1 هو النمط الكامل بعد escape_like، وليس المفتاح الخام
SELECT id, name FROM students
WHERE search_key_loose LIKE $1 ESCAPE '\';

text_pattern_ops يسرّع البادئات فقط. للاحتواء %query% استخدم pg_trgm. لا تدمج مدخل المستخدم في SQL نصياً. إذا كان الاستعلام فارغاً، لا ترسل %%؛ أعد نتيجة فارغة أو تجاوز الفلتر.

PostgREST/Supabase: اختبر R1 محلياً HTTP مباشر إلى PostgREST 14.10 + PostgreSQL 16، ووجد أن .like() يحترم فرار \ لـ % و_ و\. لم تُختبر استدعاءات Supabase SDK أو الخدمة المستضافة. المثال أعلاه يستخدم psycopg مباشرة؛ أعد اختبار إصدارك عند استخدام SDK.

الـ API

الترخيص

MIT — Devsamhan