# تحليل_مبيعات.apy
استورد بانداس باسم بد        # pandas
استورد نمباي باسم نم        # numpy
استورد سيبورن باسم رسم       # seaborn
استورد رياضيات

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

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

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

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

pip install -e ".[dev]"

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

طرق التشغيل

ثعبان ملف.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 وحدة)

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

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

طبقة الأدوات

واجهة برمجة 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
├── 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.قيمة).

خارطة الطريق

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

الوثائق

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

• 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-05-01): 0.4.0 includes the core dialect, canonical Arabic lexicon, 40+ Arabic library aliases, Arabic diagnostics, formatter, linter, Jupyter kernel, VS Code extension, and GitHub Pages docs.

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 · translated common 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. Larger work should include a spec packet or a clear issue, and any new Arabic term should start in lexicon/.

Acknowledgements

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