عن المشروع

## ما هو `liege` هو عميل Python غير متزامن لمجموعات البيانات المفتوحة التي تنشرها منصة البيانات المفتوحة (Open Data Platform) في لييج، بلجيكا. يقوم بتغليف واجهة برمجة التطبيقات (API) الخاصة بالمنصة بحيث يمكن لكود Python — عادةً داخل حلقة أحداث غير متزامنة (async event loop) — جلب السجلات ككائنات ذات أنواع محددة بدلاً من التعامل مع طلبات HTTP الخام وتحليل JSON. تم كتابة الحزمة في الأصل لاسترجاع بيانات مواقف السيارات فقط، ولكن يشير ملف README إلى أن قاعدة الكود مهيكلة بحيث يمكن إضافة مجموعات بيانات إضافية من نفس المنصة بسهولة. ## التثبيت ```bash pip install liege ``` ## مجموعات البيانات المشمولة تم توثيق مجموعتين من البيانات في ملف README: - **مواقف السيارات لذوي الاحتياجات الخاصة / Stationnement PMR** — 1062 موقعاً. - **المرائب / Les parkings voitures hors voirie** — 32 موقعاً. يتم الاستعلام عن كل مجموعة بيانات باستخدام معامل `limit` (الافتراضي 10) الذي يتحكم في عدد النتائج التي يتم إرجاعها. ### حقول مواقف ذوي الاحتياجات الخاصة `spot_id` (int), `number` (int), `address` (str), `municipality` (str), `city` (str), `status` (str), `longitude` (float), `latitude` (float), `created_at` (datetime), `updated_at` (datetime). ### حقول المرائب `name` (string), `capacity` (int), `charging_stations` (int), `address` (string), `municipality` (string), `city` (string), `provider` (string), `schedule` (string), `longitude` (float), `latitude` (float), `created_at` (datetime), `updated_at` (datetime). ## مثال على الاستخدام تم تصميم العميل كمدير سياق غير متزامن (async context manager): ```python import asyncio from liege import ODPLiege async def main() -> None: async with ODPLiege() as client: garages = await client.garages(limit=10) disabled_parkings = await client.disabled_parkings(limit=10) print(garages) print(disabled_parkings) asyncio.run(main()) ``` ## حالة استخدام موثقة يستشهد ملف README بموقع NIPKaart.nl، وهو موقع إلكتروني يرسم خرائط لمواقف السيارات لذوي الاحتياجات الخاصة باستخدام بيانات مقدمة من المستخدمين والبلديات. يعمل الموقع بشكل أساسي في هولندا ولكنه صرح بخطط لمعالجة بيانات من الخارج، وهنا يأتي دور هذا العميل. ## إعداد التطوير يستخدم المشروع Poetry لإدارة التبعيات ويتطلب Python 3.12+ بالإضافة إلى Poetry نفسه. بعد الاستنساخ: ```bash poetry install ``` يقوم Poetry بإنشاء بيئة افتراضية للتبعيات بشكل افتراضي. يتم ربط عمليات التدقيق (Linting) والاختبار عبر إطار عمل `prek` الذي يشغل الفحوصات عند كل عملية commit: ```bash poetry run prek install poetry run prek run --all-files ``` تستخدم الاختبارات pytest، مع معالجة اختبارات اللقطات (snapshot tests) بواسطة syrupy: ```bash poetry run pytest poetry run pytest --snapshot-update ``` يتم توفير تكوين Dev Container، بحيث يمكن بدء البيئة مباشرة في Visual Studio Code أو كـ GitHub CodeSpace. ## إشارات المشروع في ملف README تشير كتلة الشارات إلى مرحلة المشروع التجريبية، والصيانة المستمرة، ونشاط الـ commit الفعال، والإصدارات المنشورة على GitHub، والتوزيع على PyPI مع إحصائيات التنزيل، وحالة سير عمل البناء والأنواع، وتقارير تغطية الكود، وشارة OpenSSF Scorecard. كما يوثق المشروع إرشادات المساهمة في ملف CONTRIBUTING.md منفصل وهو مرخص بموجب رخصة MIT (حقوق الطبع والنشر 2022–2026 Klaas Schoute). ## الملاءمة هذه مكتبة عميل API صغيرة وذات غرض واحد: مفيدة عندما تحتاج إلى بيانات لييج المفتوحة (المتعلقة بمواقف السيارات حالياً) داخل تطبيق Python غير متزامن، ومفيدة كنموذج لتغليف مجموعات بيانات أخرى من نفس منصة ODP. إنها ليست مخزناً للبيانات، ولا خادماً، ولا تطبيقاً للمستخدم النهائي.