أساس (Asas)

إطار عمل أساس، أداء عالٍ، سهل التعلم، سريع البرمجة، جاهز للإنتاج

---

عن المشروع

أساس هو إطار عمل مبسّط لبناء عملاء واجهات برمجة التطبيقات (SDKs) عبر واجهة نظيفة تعتمد على المزخرفات (decorators). تقوم بوراثة عميل، ثم تُعلِّم الدوال بـ @get / @post وما إلى ذلك، ويتولّى أساس بناء الطلب والمصادقة والتحليل وإعادة المحاولة نيابةً عنك.

صُمِّم لبايثون الحديثة: دعم أصيل لـ async/await وتكامل من الدرجة الأولى مع Pydantic للتحقق من بيانات الطلب والاستجابة.

الهدف

الهدف الأساسي لأساس هو جعل تكامل واجهات البرمجة أكثر بايثونية وأناقة وقابلية للصيانة. من خلال تجريد الإطالة المعتادة في مكتبات الطلبات التقليدية، يتيح لك أساس التركيز على بنية واضحة وكود معبّر.

التثبيت

pip install asas-py

البداية السريعة

يوفّر أساس عملاء منفصلين للكود المتزامن وغير المتزامن. تعمل المزخرفات نفسها مع كليهما — إذ يكتشف أساس دوال async def تلقائيًا.

متزامنغير متزامن

from asas import AsasClient, get, Response

class MyClient(AsasClient):
    @get("/users/{id}")
    def get_user(self, response: Response, id: int):
        return response.json()

client = MyClient(base_url="https://api.example.com")
user = client.get_user(id=1)

from asas import AsasAsyncClient, get, Response

class MyAsyncClient(AsasAsyncClient):
    @get("/users/{id}")
    async def get_user(self, response: Response, id: int):
        return response.json()

async def main():
    client = MyAsyncClient(base_url="https://api.example.com")
    user = await client.get_user(id=1)
    await client.engine.aclose()

الوسيط الأول المُحقَن

تستقبل الدالة المزخرفة النتيجة المُحلَّلة بوصفها أول وسيط بعد self (وهو response أعلاه). أما الوسائط المتبقية — مثل id — فيُمرِّرها المستدعي ويُوجَّهها أساس إلى الطلب. راجع التوجيه والوسائط.

أبرز المزايا

• العملاء — عملاء متزامنون وغير متزامنين بطبقة نقل قابلة للاستبدال ومصادقة قابلة للتغيير أثناء التشغيل.
• التوجيه والوسائط — @get/@post/@put/@delete/@patch مع توجيه تلقائي للمسار والاستعلام والجسم.
• أجسام الطلب والاستجابات — نماذج Pydantic تدخل، ونماذج مُتحقَّق منها تخرج عبر response_model.
• الموارد والترقيم الصفحي — عمليات CRUD قائمة على الاصطلاح وتكرار كسول على كل سجلّ، دون أي كود لحلقة الصفحات.
• المصادقة — أساسية، وحاملة، ومفتاح API، وتجديد تلقائي، واستراتيجيات مركَّبة.
• المحرّكات وطبقات النقل — نواة مستقلّة عن النقل؛ وhttpx هو المحرّك المرجعي المرفق، مع محرّك requests اختياري عبر إضافة.
• النماذج الأساسية — فئات بيانات Request / Response / Payload بسيطة تتحدّث بها كل الطبقات.