lughat-althuban 0.3.0

لغة الثعبان — Arabic-keyword Python dialect with stdlib & library aliases, tooling, and translated tracebacks

لغة الثعبان — بايثون بالعربية الكاملة

لهجة برمجية تكتب فيها الكلمات المفتاحية والدوال المدمجة والاستثناءات والمكتبات بالعربية الكاملة. ملفات .apy تُترجم إلى بايثون القياسي في وقت التحميل وتُنفَّذ بواسطة CPython — دون تشعيب للمترجم ودون تعديل على اللغة الأصلية.

الحالة (2026-04-28): المرحلة أ مكتملة. المرحلة ب مكتملة إلى حدٍّ بعيد — 2,510 اختباراً ناجحاً على Python 3.11–3.13 في Ubuntu وmacOS وWindows. 40+ وحدة عربية مُشحونة. منظومة أدوات متكاملة (منسّق + مدقّق + نواة Jupyter + امتداد VS Code).

---

مثال متكامل — تحليل بيانات بالعربية الكاملة

# تحليل_مبيعات.apy
استورد جداول_بيانات  كـ  جب        # pandas
استورد حسابات_عددية كـ  عد        # numpy
استورد رسوم_احصائيه كـ  رسم       # seaborn
استورد رياضيات

بيانات = جب.قراءة_جيسون("مبيعات.json")
متوسط  = عد.متوسط(بيانات["الإيرادات"])
اطبع(f"متوسط الإيرادات: {رياضيات.تقريب(متوسط, 2)}")

رسم.ضبط_موضوع("darkgrid")
مخطط = رسم.خط_بياني(بيانات=بيانات, x="الشهر", y="الإيرادات")
مخطط.figure.savefig("تقرير_المبيعات.png")
اطبع("✓ تم حفظ التقرير")

$ ثعبان تحليل_مبيعات.apy
متوسط الإيرادات: 48750.32
✓ تم حفظ التقرير

---

التثبيت

يتطلب Python 3.11 أو أحدث:

git clone https://github.com/GalaxyRuler/lughat-althuban
cd lughat-althuban
pip install -e .

للتطوير مع جميع المكتبات المدعومة:

pip install -e ".[dev]"

يُثبَّت الأمر ثعبان تلقائياً. ثعبان --help وثعبان --version يعملان كما هو متوقع.

---

طرق التشغيل

ثعبان ملف.apy [مُعامِلات...]     # تشغيل ملف
ثعبان -c 'اطبع("مرحبا")'         # تنفيذ سطر مباشرةً
ثعبان - < ملف.apy                # قراءة من المدخل القياسي
ثعبان                             # البيئة التفاعلية REPL
ثعبان نسّق ملف.apy               # تنسيق الملف تلقائياً
ثعبان راجع ملف.apy               # فحص الجودة وإظهار التحذيرات

رموز الخروج: 0 نجاح، 1 خطأ في التشغيل أو الترجمة، 2 خطأ في الاستخدام.

---

استيراد وحدات .apy

# رئيسي.apy
استورد مساعد
مساعد.مرحبا("عالم")

# مساعد.apy
دالة مرحبا(اسم):
    اطبع(f"مرحبا يا {اسم}")

الحزم المختلطة .py / .apy تعمل — ملفات Python التي تستورد وحدات .apy ترى الأسماء المترجمة والمُطبَّعة.

---

رسائل الخطأ بالعربية

$ ثعبان -c '1 / 0'
تتبع_الأخطاء (المكدس الأحدث آخرا):
  ملف "<string>", سطر 1, في <الوحدة>
خطا_القسمه_على_صفر: القسمة على صفر

38 نوع استثناء قياسي و~30 رسالة مترجمة. الأنواع غير المعروفة تمر كما هي.

---

الوحدات العربية — استيراد المكتبات بأسماء عربية

المكتبة القياسية (21 وحدة)

الاسم العربي	وحدة Python	الاسم العربي	وحدة Python
نظام_تشغيل	os	رياضيات	math
مسار_مكتبه	pathlib	احصاء	statistics
نظام	sys	عشوائيات	random
مجموعات	collections	تسجيل	logging
ادوات_تكرار	itertools	اتزامن	asyncio
ادوات_داليه	functools	هاشلب	hashlib
مكتبة_تاريخ	datetime	مجاري	io
وقت_نظام	time	مدير_سياق	contextlib
روزنامه	calendar	قاعدة_بيانات	sqlite3
جيسون	json	تعابير_نمطيه	re
ملفات_csv	csv

علوم وبيانات (6 حزم)

الاسم العربي	حزمة Python
حسابات_عددية	numpy
جداول_بيانات	pandas
رسوم_بيانيه	matplotlib
رسوم_احصائيه	seaborn
علوم_حسابيه	scipy
تعلم_آلي	scikit-learn

ويب وشبكات (4 حزم)

الاسم العربي	حزمة Python
قارورة	flask
طلبات	requests
طلبات_غير_متزامنه	aiohttp
واجهه_برمجيه	fastapi

تعلم آلي (1 حزمة)

الاسم العربي	حزمة Python
مشعل	torch

---

طبقة الأدوات

الأداة	الأمر	الوصف
المنسِّق	ثعبان نسّق ملف.apy	تنسيق تلقائي: المسافات البادئة، والتباعد، وأسلوب التعليقات
المدقِّق	ثعبان راجع ملف.apy	تشخيصات: W001–W004، E001، I001
نواة Jupyter	pip install -e ".[kernel]"	تشغيل دفاتر .apy في Jupyter
امتداد VS Code	editors/vscode/	إبراز صياغي لملفات .apy
إضافة pytest	مُدمجة تلقائياً	اكتشاف وتشغيل ملفات اختبار .apy

---

واجهة برمجة Python

from arabicpython import (
    install,                       # تثبيت خطاف استيراد .apy
    uninstall,
    run_repl,                      # تشغيل البيئة التفاعلية REPL
    install_excepthook,            # توجيه الاستثناءات غير الملتقطة للمترجم
    uninstall_excepthook,
    format_translated_exception,   # تنسيق مجموعة (نوع، قيمة، تتبع) بالعربية
)
from arabicpython.formatter import format_source, format_file
from arabicpython.linter import lint_source, Diagnostic

---

هيكل المشروع

lughat-althuban/
├── arabicpython/              حزمة المحوِّل
│   ├── aliases/               تعيينات TOML (40+ وحدة)
│   ├── formatter.py           المنسِّق التلقائي
│   └── linter.py              محرك التدقيق والتشخيص
├── arabicpython_kernel/       حزمة نواة Jupyter
├── editors/vscode/            امتداد VS Code
├── tools/                     مولد القواعد النحوية وأدوات التطوير
├── decisions/                 سجلات قرارات المعمارية (ADRs)
├── dictionaries/              مرجع الكلمات المفتاحية ar-v1
├── specs/                     حزم المواصفات للتنفيذ
├── tests/                     مجموعة pytest (2510 نجاح، 45 تجاوز)
├── examples/                  برامج .apy قابلة للتشغيل
├── docs/
│   ├── ar/                    الوثائق العربية
│   └── wiki/                  ويكي المرجع الشامل
└── apps/                      تطبيقات عرض متكاملة

---

المعمارية

المصدر يمر عبر pretokenize (الأرقام العربية ← ASCII، ترميز علامات الترقيم، رفض محارف bidi) ← tokenize الخاصة ببايثون ← معيد كتابة NAME يستشير القاموس العربي↔Python القانوني ← untokenize ← compile ← exec. لا إعادة كتابة لشجرة AST، ولا تشعيب لـ CPython. نفس الأنبوب يدعم كل نقاط الدخول (CLI، REPL، خطاف الاستيراد).

قرارات رئيسية: decisions/0001-architecture.md | decisions/0004-normalization-policy.md

قواعد التطبيع: أ/إ/آ → ا، ة → ه (في النهاية)، ى → ي (في النهاية). جميع مفاتيح TOML يجب أن تجتاز normalize_identifier().

---

نموذج التطوير

• المخطط (Claude): يكتب سجلات القرارات، يُنسِّق القواميس، يُؤلِّف حزم المواصفات، يراجع التغييرات.
• المنفِّذ: يقرأ الحزم في specs/NNNN-*.md، يكتب الكود، يُشغِّل الاختبارات.

كل وحدة عمل هي حزمة مواصفات مكتفية بنفسها. انظر specs/0000-template.md وspecs/INDEX.md.

---

القيود المعروفة

• from . import x في __init__.apy داخل حزمة — الحل البديل: import pkg.sub as sub.
• الوصول إلى السمات من .py إلى .apy يجب أن يستخدم شكل المعرِّف المُطبَّع وفق ADR-0004 (مثل module.قيمه لا module.قيمة).

---

خارطة الطريق

المرحلة	المحتوى	الحالة
0	قرارات التصميم (8 سجلات ADR)	✅ مكتملة
أ	اللهجة الأساسية: التجهيز المسبق، التطبيع، الترجمة، CLI، REPL، خطاف الاستيراد، رسائل الخطأ	✅ مكتملة
ب	النظام البيئي: 40+ وحدة عربية، منسِّق، مدقِّق، نواة Jupyter، VS Code، دليل تعليمي	🟡 مكتملة إلى حدٍّ بعيد — المساهمون مرحب بهم
ج	متقدم: خادم LSP، ملعب ويب، تكامل مدير الحزم	📋 مخطط لها

انظر ROADMAP-PHASE-B.md وCONTRIBUTING.md.

---

الوثائق

الوثيقة	الوصف
دليل البدء الشامل	من "مرحبا بالعالم" إلى الاستيراد — خطوة بخطوة
دليل البدء الموسَّع	شرح تفصيلي كامل مع أمثلة وتسلسل هندسي (B-060)
كتاب الوصفات	عشر وصفات قائمة بذاتها قابلة للتشغيل المباشر
مسرد المصطلحات	35+ مصطلح حاسوبي بتعريفات عربية فصيحة
نظرة عامة على المشروع	المعمارية، هيكل المشروع، خارطة الطريق
مرجع المكتبة القياسية	جميع الوحدات القياسية العربية مع أمثلة
ويكي المشروع	دليل شامل: الكلمات المفتاحية، المكتبات، الأدوات، الأسئلة الشائعة
دليل المساهمة	كيفية إضافة وحدات ومساهمات الكود
سجل التغييرات	ما الذي تغيّر في كل إصدار
خارطة الطريق	الحزم القادمة وحالتها

---

الإقرارات والشكر

• zhpy (gasolin، 2014) — لهجة بايثون الصينية القائمة على التجزئة المعجمية التي يعتمد هذا المشروع معمارياً عليها.
• قلب لـ Ramsey Nasser — النقد الذي يأخذه هذا المشروع بجدية.
• Hedy — دليل على نجاح التعليم متعدد اللغات والمتدرج في النحو على نطاق واسع.
• السوار / مجمع اللغة العربية (KSAA) — واجهة برمجية للمعجم العربي تُستخدم في أبحاث المصطلحات.

---

لغة الثعبان — Arabic Python (English summary)

The primary documentation above is in Arabic — the language this project is built for. Below is a concise English reference for contributors and readers not yet fluent in Arabic.

A Python dialect where keywords, built-ins, exceptions, and popular libraries are all written in Arabic. .apy files are translated to standard Python at import time and executed by CPython — no interpreter fork, no language modification.

Status (2026-04-28): Phase A complete. Phase B substantially complete — 2,510 tests passing across Python 3.11–3.13 on Ubuntu / macOS / Windows.

License: Apache-2.0.

---

Install

git clone https://github.com/GalaxyRuler/lughat-althuban
cd lughat-althuban
pip install -e .          # installs the ثعبان console script
pip install -e ".[dev]"   # all optional library aliases

---

Run

ثعبان script.apy          # run a file
ثعبان -c 'اطبع("مرحبا")'  # inline snippet
ثعبان                      # interactive REPL
ثعبان نسّق script.apy      # auto-format
ثعبان راجع script.apy      # lint

---

Key facts

• 38 Arabic exception names · ~30 translated interpreter messages
• 21 stdlib alias modules · 6 science/data · 4 web · 1 ML (40+ total)
• Formatter · Linter · Jupyter kernel · VS Code extension · pytest plugin — all ship in this repo
• Normalization: أ/إ/آ → ا, final ة → ه, final ى → ي

---

Contributing

See CONTRIBUTING.md. Arabic commit messages are preferred. Every unit of work is a self-contained spec packet in specs/.

Acknowledgements

zhpy (2014) · قلب by Ramsey Nasser · Hedy · Siwar/KSAA Arabic lexicon API.