From dccfc2dc9bb0cea3275a6ee4e47162689ded5977 Mon Sep 17 00:00:00 2001 From: Khaldosh249 Date: Thu, 9 Jan 2025 18:38:37 +0300 Subject: [PATCH 1/2] New translation: lang-ar: docs/ar/docs/index.md --- docs/ar/docs/index.md | 497 ++++++++++++++++++++++++++++++++++++++++++ docs/ar/mkdocs.yml | 1 + docs/en/mkdocs.yml | 2 + 3 files changed, 500 insertions(+) create mode 100644 docs/ar/docs/index.md create mode 100644 docs/ar/mkdocs.yml diff --git a/docs/ar/docs/index.md b/docs/ar/docs/index.md new file mode 100644 index 000000000..759c27e8b --- /dev/null +++ b/docs/ar/docs/index.md @@ -0,0 +1,497 @@ +# FastAPI + + + +

+ FastAPI +

+

+ إطار عمل FastAPI, عالي الأداء, سهل التعلم, سريع في البرمجة وجاهز للإطلاق +

+

+ + Test + + + Coverage + + + Package version + + + Supported Python versions + +

+ +--- + +**الوثائق**: https://fastapi.tiangolo.com + +**كود المصدر**: https://github.com/fastapi/fastapi + +--- + +FastAPI هو إطار عمل ويب حديث, سريع (عالي الأداء), لإنشاء واجهة برمجة التطبيقات (APIs) باستخدام لغة بايثون (Python), معتمدًا على تلميحات النوع القياسية في Python. + + +المميزات الرئيسية: + +* **سريع**: أداء عالي جداً, يضاهي **NodeJS** و **Go** (بفضل Starlette و Pydantic). [أحد اسرع أُطر العمل في بايثون](#_11). +* **سريع في البرمحة**: زيادة سرعة تطوير الميزات بحوالي 200% إلى 300%. * +* **أخطاء أقل**: تقليل حوالي 40% من الأخطاء التي يسببها الإنسان (المطور). * +* **بديهي**: دعم محرر رائع. الإكمال التلقائي (Completion) في أي مكان. وقت أقل في حل الأخطاء. +* **سهل**: صُمم ليكون سهل الاستخدام والتعلم. وقت أقل لقراءة الوثائق. +* **مختصر**: تقليل تكرار الأكواد. ميزات متعددة عند تعريف كل معلمة (parameter). أخطاء أقل. +* **قوي**: أحصل على كود جاهز للإطلاق. مع وثائق تفاعلية تلقائية. +* **مبني على المعايير**: مبنية بناءاً على (ومتوافقة كلياً مع) المعايير المفتوحة لـ APIs: OpenAPI (معروفة مسبقاً بـ Swagger) و JSON Schema. + +* تقديرات بناءً على اختبارات لفريق تطوير داخلي قام ببناء تطبيقات إنتاجية. + +## الرعاة + + + +{% if sponsors %} +{% for sponsor in sponsors.gold -%} + +{% endfor -%} +{%- for sponsor in sponsors.silver -%} + +{% endfor %} +{% endif %} + + + +الرعاة الآخرون + +## الآراء + +"_[...] أنا استخدم **FastAPI** بشكل مكثف هذه الأيام. [...] في الواقع أخطط لاستخدامه في جميع خدمات **تعلم الآلة التي يقدمها فريقي في مايكروسوفت**. يتم دمج بعضها في منتج **Windows** وبعض منتجات **Office**._" + +
كبير خان - Microsoft (المرجع)
+ +--- + +"_لقد اعتمدنا مكتبة **FastAPI** لإنشاء خادم **REST** يمكن الاستعلام منه للحصول على **التنبؤات**. [لـ Ludwig]_" + +
بيرو مولينو, ياروسلاف دودين, وساي سومانت ميرالا - Uber (المرجع)
+ +--- + +"_يسر **Netflix** أن تعلن عن إصدار مفتوح المصدر لإطار عمل **إدارة الأزمات**: **Dispatch**! [تم بناؤه باستخدام **FastAPI**]_" + +
كيفن جليسون, مارك فيلانوفا, وفورست مونسن - Netflix (المرجع)
+ +--- + +"_أنا متحمس للغاية بشأن **FastAPI**. إنه ممتع جدًا!_" + +
برايان أوكن - مضيف بودكاست Python Bytes (المرجع)
+ +--- + +"_بصراحة، ما قمت ببنائه يبدو متينًا ومصقولًا للغاية. من نواحٍ عديدة, إنه ما كنت أرغب أن يكون عليه **Hug** - من الملهم حقًا رؤية شخص ما يبني شيئًا كهذا._" + +
تيموثي كروسلي - مبتكر Hug (المرجع)
+ +--- + +"_إذا كنت تبحث عن تعلم **إطار عمل حديث** لبناء واجهات REST APIs, عليك التحقق من **FastAPI** [...] إنه سريع وسهل الاستخدام وسهل التعلم [...]_" + +"_لقد انتقلنا إلى استخدام **FastAPI** في **واجهاتنا البرمجية** [...] أعتقد أنك ستحبه [...]_" + +
إينيس مونتاني - ماثيو هونيبال - مؤسسو Explosion AI - مبتكرو spaCy (المرجع) - (المرجع)
+ +--- + +"_إذا كان أي شخص يبحث عن بناء واجهات برمجية (API) للإنتاج باستخدام Python, أوصي بشدة بـ **FastAPI**. إنه **مصمم بشكل جميل**, و**سهل الاستخدام** و **قابل للتوسع بشكل كبير**, لقد أصبح **عنصراً أساسياً** في استراتيجيتنا التطويرية الأولى الخاصة بـ API ويقود العديد من الأتمتة والخدمات مثل Virtual TAC Engineer الخاص بنا._" + +
ديون بيلزبري - Cisco (المرجع)
+ +--- + +## **Typer**, يعتبر FastAPI الخاص بواجهات الأوامر النصية (CLIs) + + + +إذا كنت تقوم ببناء تطبيق واجهة أوامر نصية (CLI) للاستخدام في الـ (terminal) بدلاً من API لتطبيقات ويب، يمكنك التحقق من **Typer**. + +**Typer** هو الأخ الأصغر لـ FastAPI. وهو مصمم ليكون **FastAPI لواجهة الأوامر النصية (CLI)**. ⌨️ 🚀 + +## المتطلبات + +يعتمد FastAPI على المكتبات القوية: + +* Starlette لجانب الويب. +* Pydantic لجانب البيانات. + +## التثبيت + +قم بإنشاء وتفعيل بيئة افتراضية (virtual environment) وبعد ذلك قم بتثبيت FastAPI: + +
+ +```console +$ pip install "fastapi[standard]" + +---> 100% +``` + +
+ +**ملاحظة**: تحقق من وضع `"fastapi[standard]"` بين علامتين تنصيص للتأكد أنها تعمل في جميع الـ (terminals). + +## مثال + +### قم بإنشائه + +* أنشء ملف `main.py` به: + +```Python +from typing import Union + +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +def read_item(item_id: int, q: Union[str, None] = None): + return {"item_id": item_id, "q": q} +``` + +
+أو async def... + +إذا كان برنامجك يستخدم `async` / `await`, قم باستخدام `async def`: + +```Python hl_lines="9 14" +from typing import Union + +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +async def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +async def read_item(item_id: int, q: Union[str, None] = None): + return {"item_id": item_id, "q": q} +``` + +**ملاحظة**: + +إذا كنت لا تعرف, تحقق من قسم _"على عجلة؟"_ حول `async` و `await` في المستندات. + +
+ +### قم بتشغيله + +قم بتشغيل الخادم باستخدام: + +
+ +```console +$ fastapi dev main.py + + ╭────────── FastAPI CLI - Development mode ───────────╮ + │ │ + │ Serving at: http://127.0.0.1:8000 │ + │ │ + │ API docs: http://127.0.0.1:8000/docs │ + │ │ + │ Running in development mode, for production use: │ + │ │ + │ fastapi run │ + │ │ + ╰─────────────────────────────────────────────────────╯ + +INFO: Will watch for changes in these directories: ['/home/user/code/awesomeapp'] +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +INFO: Started reloader process [2248755] using WatchFiles +INFO: Started server process [2248757] +INFO: Waiting for application startup. +INFO: Application startup complete. +``` + +
+ +
+عن الأمر fastapi dev main.py... + +الأمر `fastapi dev` يقوم بقراءة الملف `main.py`, يتعرف على تطبيق **FastAPI** الموجود بداخله, ويقوم بتشغيل الخادم بـ Uvicorn. + +بشكل افتراضي, `fastapi dev` ستبدأ مع auto-reload (إعادة التحميل التلقائية) مفعلة للبيئة المحلية. + +يمكنك قراءة المزيد على مستندات FastAPI CLI. + +
+ +### تحقق من النتيجة + +افتح المتصفح على http://127.0.0.1:8000/items/5?q=somequery. + +سترى استجابة JSON بالشكل التالي: + +```JSON +{"item_id": 5, "q": "somequery"} +``` + +لقد قمت بالفعل بإنشاء واجهة برمجة تطبيقات (API) تقوم بـ: + +* استقبال طلبات HTTP على _المسارين_ `/` و `/items/{item_id}`. +* كلا المسارين يدعمان عمليات `GET` (معروفة أيضا باسم HTTP _methods_). +* _المسار_ `/items/{item_id}` يحتوي على _معلمة مسار_ `item_id` التي يجب أن تكون من النوع `int`. +* _المسار_ `/items/{item_id}` يحتوي على _معلمة استعلام_ اختيارية `q` من النوع `str`. + +### وثائق API التفاعلية + +الآن انتقل إلى http://127.0.0.1:8000/docs. + +سترى وثائق API التفاعلية التلقائية (مقدمة بواسطة Swagger UI): + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) + +### وثائق API البديلة + +والآن, انتقل إلى الرابط http://127.0.0.1:8000/redoc. + +سترى الوثائق التلقائية البديلة (مقدمة بواسطة ReDoc): + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) + +## تحديث المثال + +قم بتعديل الملف `main.py` ليتمكن من استقبال جسم (body) من طلب `PUT`. + +يمكنك تعريف الجسم باستخدام الأنواع القياسية في Python بفضل مكتبة Pydantic. + +```Python hl_lines="4 9-12 25-27" +from typing import Union + +from fastapi import FastAPI +from pydantic import BaseModel + +app = FastAPI() + + +class Item(BaseModel): + name: str + price: float + is_offer: Union[bool, None] = None + + +@app.get("/") +def read_root(): + return {"Hello": "World"} + + +@app.get("/items/{item_id}") +def read_item(item_id: int, q: Union[str, None] = None): + return {"item_id": item_id, "q": q} + + +@app.put("/items/{item_id}") +def update_item(item_id: int, item: Item): + return {"item_name": item.name, "item_id": item_id} +``` + +الأمر `fastapi dev` يجعل الخادم يقوم بإعادة التحميل تلقائياً. + +### تحديث وثائق API التفاعلية + +انتقل الآن إلى http://127.0.0.1:8000/docs. + +* ستكون وثائق API التفاعلية قد تم تحديثها تلقائياً, متضمنةً الجسم (body) الجديد. + +![Swagger UI](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) + +* أضغط على الزر "Try it out", الذي يتيح لك تعبئة المعلمات (parameters) والتفاعل مباشرة مع API: + +![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-04-swagger-03.png) + +* بعد ذلك قم بضغط الزر "Execute", ستقوم واجهة المستخدم بالتواصل مع واجهة برمجة التطبيقات (API) الخاصة بك, إرسال المعلمات (parameters), واستلام النتائج، وعرضها على الشاشة: + +![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-05-swagger-04.png) + +### تحديث وثائق API البديلة + +الآن انتقل إلى الرابط http://127.0.0.1:8000/redoc. + +* الوثائق البديلة أيضا ستظهر المعلمة (parameter) الجديدة والجسم (body) الجديد: + +![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) + +### الملخص + +باختصار، يمكنك تحديد أنواع المعلمات (parameters) والجسم (body) وغيرها **مرة واحدة** كمعلمات للدالة (function). + +يتم ذلك باستخدام الأنواع (types) القياسية الحديثة في Python + +لا حاجة لتعلم صياغة (syntax) جديدة أو استخدام methods أو classes خاصة بمكتبة معينة. + +فقط استخدم **Python** القياسي. + +على سبيل المثال, لتعريف عدد صحيح `int`: + +```Python +item_id: int +``` + +أو تعريف نموذج (model) معقد مثل `Item`: + +```Python +item: Item +``` + +...وباستخدام هذا التحديد البسيط، تحصل على: + +* دعم المحرر, ويتضمن: + * الإكمال التلقائي (Completion). + * فحص الأنواع (Type checks). +* التحقق من صحة البيانات: + * أخطاء تلقائية وواضحة عند وجود بيانات غير صالحة. + * تحقق من البيانات حتى في JSON المتداخلة بعمق (nested JSON). +* تحويل (Conversion) البيانات المدخلة: القادمة من الشبكة إلى بيانات وأنواع Python. والتي يتم قراءتها من: + * JSON. + * معلمات المسار (Path parameters). + * معلمات الاستعلامات (Query parameters). + * قراءة من ملفات تعريف الارتباط (Cookies). + * قراءة من رؤوس الطلبات (Headers). + * قراءة من النماذج (Forms). + * قراءة من الملفات (Files). +* تحويل (Conversion) البيانات المخرجة: تحويل من بيانات وأنواع Python إلى بيانات الشبكة (مثل JSON): + * تحويل أنواع (types) Python (`str`, `int`, `float`, `bool`, `list`, إلخ). + * كائنات `datetime`. + * كائنات `UUID`. + * نماذج قواعد البيانات (Database models). + * ...والكثير غيرها. +* وثائق API التفاعلي التلقائي, متضمناً واجهتي مستخدم: + * Swagger UI. + * ReDoc. + +--- + +بالعودة إلى مثال الكود السابق, **FastAPI** سيقوم بما يلي: + +* التحقق من وجود `item_id` في المسار لطلبات `GET` و `PUT`. +* التأكد من أن `item_id` هو من النوع `int` في طلبات `GET` و `PUT`. + * إذا لم تكن كذلك, سيظهر للعميل خطأ واضح ومفيد. +* التحقق من وجود معلمة (parameter) الاستعلام الاختياري `q` (كما في `http://127.0.0.1:8000/items/foo?q=somequery`) في طلبات `GET`. + * بما أن المعلمة `q` تم تعريفها بقيمة افتراضية `= None`, إذا هي اختيارية. + * بدون `None` ستكون هذه المعلمة مطلوبة (كما هو الحال مع الجسم (body) في طلبات `PUT`). +* في طلبات `PUT` لـ `/items/{item_id}`, قراءة الجسم كـ JSON: + * التأكد من وجود الصفة (attribute) المطلوبة `name` والتي يجب أن تكون من نوع `str`. + * التأكد من وجود الصفة (attribute) المطلوبة `price` والتي يجب أن تكون من نوع `float`. + * التأكد من وجود الصفة (attribute) الاختيارية `is_offer`, والتي يجب أن تكون من نوع `bool`, إذا كانت موجودة. + * كل هذا سيعمل مع كائنات JSON المتداخلة بشكل عميق (deeply nested JSON). +* التحويل من والى JSON تلقائياً. +* توثيق كل شيء بـ OpenAPI, والذي يمكن استخدامه بواسطة: + * أنظمة التوثيق التفاعلية. + * أنظمة إنشاء أكواد العميل تلقائيًا, للغات متعددة. +* توفر مباشرة واجهتي ويب للتوثيق التفاعلي. + +--- + +لم نخدش سوى السطح فقط، لكنك أصبحت تفهم بالفعل الفكرة العامة عن كيفية عمل كل شيء. + +جرب تغيير السطر التالي: + +```Python + return {"item_name": item.name, "item_id": item_id} +``` + +...من: + +```Python + ... "item_name": item.name ... +``` + +...إلى: + +```Python + ... "item_price": item.price ... +``` + +...وستلاحظ كيف أن محررك سيكمل تلقائياً الخصائص (attributes) ويعرف أنواعها: + +![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) + +لمثال أكثر اكتمالا ويتضمن المزيد من الخصائص, قم بزيارة البرنامج التعليمي - دليل المستخدم. + +**تنبيه الكبح**: يتضمن البرنامَج التعليمي - دليل المستخدم: + +* تعريف **المعلمات (parameters)** من أماكن أخرى مثل: **headers**, **cookies**, **form** و **files**. +* كيفية ضبط **قيود التحقق** مثل `maximum_length` أو `regex` (استخدام التعبيرات النمطية). +* نظام قوي وسهل الاستخدام لـ **حقن التبعيات (Dependency Injection)**. +* الأمان والمصادقة (Security and authentication), يتضمن دعم **OAuth2** مع مصادقة **JWT tokens** و **HTTP Basic**. +* تقنيات متقدمة (بنفس السهولة) لتعريف **نماذج JSON المتداخلة بعمق (deeply nested JSON models)** (بفضل Pydantic). +* تكامل **GraphQL** مع مكتبة Strawberry والمكتبات الأخرى. +* ميزات إضافية أخرى (بفضل Starlette) مثل: + * **WebSockets** + * اختبارات (tests) سهلة للغاية تعتمد على HTTPX و `pytest` + * **CORS** + * **جلسات الكوكيز (Cookie Sessions)** + * ...والمزيد. + +## الأداء + +تظهر معايير TechEmpower المستقلة أن تطبيقات **FastAPI** التي تعمل تحت Uvicorn واحدة من أسرع أطر العمل المتاحة في Python, مباشرة بعد Starlette و Uvicorn (مستخدمان داخلياً بواسطة FastAPI). (*) + +لفهم المزيد عن هذا, يمكنك الاطلاع على القسم المعايير (Benchmarks). + +## التبعيات (Dependencies) + +يعتمد FastAPI على Pydantic و Starlette. + +### تبعيات `standard` (التبعيات القياسية) + +عند تثبيت FastAPI بالأمر `pip install "fastapi[standard]"` فإنها تتضمن مجموعة التبعيات الاختيارية القياسية (`standard`): + +تستخدم بواسطة Pydantic: + +* email-validator - للتحقق من صحة عناوين البريد الإلكتروني. + +تستخدم بواسطة Starlette: + +* httpx - مطلوبة إذا كنت تريد استخدام `TestClient`. +* jinja2 - مطلوبة إذا كنت تريد استخدام تكوين القالب الافتراضي. +* python-multipart - مطلوب لدعم تحليل "(parsing)" النماذج, باستخدام `request.form()`. + +تستخدم بواسطة FastAPI / Starlette: + +* uvicorn - الخادم الذي يُحمّل ويخدم تطبيقك. يتضمن `uvicorn[standard]`, مع تبعيات إضافية (مثل `uvloop`) لتحسين الأداء. +* `fastapi-cli` - لتوفير أوامر `fastapi`. + +### بدون تبعيات `standard` (بدون التبعيات القياسية) + +إذا كنت لا تريد تضمين التبعيات القياسية (`standard`) الاختيارية, يمكنك التثبيت بالأمر `pip install fastapi` بدلاً عن `pip install "fastapi[standard]"`. + +### تبعيات اختيارية إضافية + +قد ترغب في تثبيت بعض التبعيات الإضافية وفقًا لاحتياجاتك. + +تبعيات إضافية لـ Pydantic: + +* pydantic-settings - لإدارة الإعدادات. +* pydantic-extra-types - لأنواع إضافية يمكن استخدامها مع Pydantic. + +تبعيات إضافية لـ FastAPI: + +* orjson - مطلوب إذا كنت تريد استخدام `ORJSONResponse`. +* ujson - مطلوب إذا كنت تريد استخدام `UJSONResponse`. + +## الترخيص + +هذا المشروع مرخص بموجب شروط رخصة MIT. diff --git a/docs/ar/mkdocs.yml b/docs/ar/mkdocs.yml new file mode 100644 index 000000000..de18856f4 --- /dev/null +++ b/docs/ar/mkdocs.yml @@ -0,0 +1 @@ +INHERIT: ../en/mkdocs.yml diff --git a/docs/en/mkdocs.yml b/docs/en/mkdocs.yml index e9a639d0b..22adb72bd 100644 --- a/docs/en/mkdocs.yml +++ b/docs/en/mkdocs.yml @@ -342,6 +342,8 @@ extra: alternate: - link: / name: en - English + - link: /ar/ + name: ar - اللغة العربية - link: /az/ name: az - azərbaycan dili - link: /bn/ From b832f319cb39b79bd369c268721ad7eb8c7407cf Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 9 Jan 2025 15:48:00 +0000 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=8E=A8=20[pre-commit.ci]=20Auto=20for?= =?UTF-8?q?mat=20from=20pre-commit.com=20hooks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/ar/docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ar/docs/index.md b/docs/ar/docs/index.md index 759c27e8b..d1e9e8d12 100644 --- a/docs/ar/docs/index.md +++ b/docs/ar/docs/index.md @@ -309,7 +309,7 @@ def update_item(item_id: int, item: Item): الأمر `fastapi dev` يجعل الخادم يقوم بإعادة التحميل تلقائياً. -### تحديث وثائق API التفاعلية +### تحديث وثائق API التفاعلية انتقل الآن إلى http://127.0.0.1:8000/docs.