الصفحة الرئيسية>المتعلقة بالبرمجة>شفرة المصدر الأخرى
تنزيل

اقرأ أحدث الوثائق - استعراض مستودع رمز GitHub

يهدف Hug إلى جعل واجهات برمجة تطبيقات Python التي تحركها بسيطة قدر الإمكان ، ولكن ليس أبسط. نتيجة لذلك ، فإنه يبسط بشكل كبير تطوير Python API.

أهداف تصميم العناق:

  • اجعل تطوير واجهة برمجة تطبيقات Python مدفوعة كتعريف مكتوب.

  • يجب أن يشجع الإطار الكود الذي يواجه الذات.

  • يجب أن يكون سريعًا. يجب ألا يشعر المطور أبدًا بالحاجة إلى البحث عن مكان آخر لأسباب الأداء.

  • يجب أن تكون اختبارات كتابة واجهات برمجة التطبيقات المكتوبة على أعلى من العناق سهلة وبديهية.

  • السحر الذي تم القيام به مرة واحدة ، في إطار API ، أفضل من دفع المشكلة التي تم تعيينها إلى مستخدم إطار API.

  • كن أساسًا لتوبيس الجيل القادم Python ، حيث يحتضن أحدث التقنيات.

نتيجة لهذه الأهداف ، Hug هو Python 3+ فقط وبناء على مكتبة HTTP عالية الأداء في Falcon

دعم تنمية العناق

احصل على العناق المدعوم بشكل احترافي مع اشتراك Tidelift

يتوفر الدعم المهني للعناق كجزء من اشتراك Tidelift. يمنح TideLift فرق تطوير البرمجيات مصدرًا واحدًا لشراء وصيانة برامجها ، مع تأكيدات احترافية من الخبراء الذين يعرفون ذلك بشكل أفضل ، مع الاندماج بسلاسة مع الأدوات الحالية.

تثبيت عناق

تثبيت العناق بسيط مثل:

 PIP3 تثبيت عناق -الترقية

من الناحية المثالية ، ضمن بيئة افتراضية.

ابدء

قم بإنشاء مثال API بنقطة نهاية بسيطة في بضعة أسطر فقط.

 # filename: happy_birthday.py "" A Basic (وظيفة واحدة) API مكتوبة باستخدام Hug "" Import [email protected] ('/happy_birthday') def happy_birthday (الاسم ، العمر: hug.types.number = 1):
    "" يقول عيد ميلاد سعيد للمستخدم "" إرجاع "Happy {Age} عيد ميلاد {name}!".

للتشغيل ، من نوع سطر الأوامر:

 عناق -f happy_birthday.py

يمكنك الوصول إلى المثال في متصفحك على: localhost:8000/happy_birthday?name=hug&age=1 . ثم تحقق من الوثائق الخاصة بـ API في localhost:8000/documentation

يمكن أيضًا ترميز المعلمات في عنوان URL (تحقق من happy_birthday.py للمثال بأكمله).

 @Hug.get ('/Greet/{event}') Def Greet (الحدث: Str): "" "" تحية بشكل مناسب (من http://blog.ketchum.com/how-to-write-10-0-common-holiday -الجسام/) "" "تحياتي =" سعيد "إذا حدث ==" عيد الميلاد ": تحية =" MERRY "if event ==" kwanzaa ": تحياتي =" Joyous "if event ==" Wishes ": MEREENTINGS =" WARD "العودة" {تحية} {event}! "

الذي ، بمجرد تشغيل الخادم على النحو الوارد أعلاه ، يمكنك استخدام بهذه الطريقة: 

curl http://localhost:8000/greet/wishes
"Warm wishes!"

الإصدار مع عناق

 # filename: versioning_example.py "" مثال بسيط لمكالمة API Hug مع الإصدار "" import [email protected] ('/echo' ، الإصدارات = 1) def echo (text): return [email protected] ('/echo' ، الإصدارات = المدى (2 ، 5)) def echo (text): return "echo: {text}".

لتشغيل المثال:

 Hug -f versioning_example.py

ثم يمكنك الوصول إلى المثال من localhost:8000/v1/echo?text=Hi / localhost:8000/v2/echo?text=Hi أو الوصول إلى الوثائق الخاصة بـ API من localhost:8000

ملاحظة: يدعم الإصدار في Hug تلقائيًا كلاً من رأس الإصدار وكذلك المواصفات المباشرة القائمة على عنوان URL.

اختبار عناق واجهات برمجة التطبيقات

لا يعانق ديكورات Hug's http وظائفك الأصلية. هذا يجعل اختبار عناق واجهات برمجة التطبيقات بسيطة مثل اختبار أي وظائف بيثون أخرى. بالإضافة إلى ذلك ، هذا يعني أن التفاعل مع وظائف API الخاصة بك في رمز Python الآخر هو مستقيم إلى الأمام مثل استدعاء وظائف Python فقط API. عناق يجعل من السهل اختبار كومة Python الكاملة من واجهة برمجة التطبيقات الخاصة بك باستخدام وحدة hug.test :

 استيراد gugimport happy_birthdayhug.test.get (happy_birthday ، 'Happy_Birthday' ، {'name': 'timothy' ، 'age': 25}) # إرجاع كائن استجابة

يمكنك استخدام كائن Response هذا للاختبار التأكيدات (راجع test_happy_birthday.py ):

 def tests_happy_birthday (): response = hug.test.get (happy_birthday ، 'happy_birthday' ، {'name': 'timothy' ، 'age': 25})

الجري مع الخوادم الأخرى القائمة على WSGI

يعرض Hug طريقة سحرية __hug_wsgi__ على كل وحدة API تلقائيًا. يجب أن يكون تشغيل API المستند إلى العناق على أي خادم WSGI قياسي بسيطًا مثل الإشارة إلى module_name : __hug_wsgi__ .

على سبيل المثال:

 uwsgi-http 0.0.0.0:8000-أمثلة ملفوف/hello_world.py-callable __hug_wsgi__

لتشغيل Hello World Hug Example API.

لبنات بناء واجهة برمجة تطبيقات عناق

عند إنشاء واجهة برمجة تطبيقات باستخدام إطار Hug ، ستستخدم المفاهيم التالية:

get ديكورات الأسلوب ، post ، update ، وما إلى ذلك ، على الأسلوب HTTP الذين يعرضون وظيفة Python الخاص بك كأبي مع الحفاظ على طريقة Python الخاصة بك دون تغيير

 @hug.get () # <- هل طريقة العناق decoratordef hello_world (): return "Hello"

يستخدم Hug هيكل الوظيفة التي تزينها لإنشاء وثائق لمستخدمي واجهة برمجة التطبيقات تلقائيًا. يمرض Hug دائمًا طلبًا واستجابة ومتغير API_Version إلى وظيفتك إذا تم تعريفها في تعريف وظيفتك.

اكتب وظائف التعليقات التوضيحية التي يتم إرفاقها اختياريًا بوسائط الأساليب الخاصة بك لتحديد كيفية التحقق من الوسيطة وتحويلها إلى نوع بيثون

 @hug.get () def math (number_1: int ، number_2: int): #the: int بعد كلتا الوسيطتين هو نوع التعليق التوضيحي number_1 + number_2

اكتب التعليقات التوضيحية أيضًا تتغذى على توليد الوثائق التلقائي لـ hug للسماح لمستخدمي واجهة برمجة التطبيقات بمعرفة البيانات التي يجب توفيرها.

توجيهات الوظائف التي يتم تنفيذها باستخدام بيانات الطلب / الاستجابة بناءً على طلبها كوسيطة في API_Function. تنطبق هذه كمعلمات إدخال فقط ، ولا يمكن تطبيقها حاليًا كتنسيقات أو تحولات الإخراج.

 @hug.get () def test_time (hug_timer): return {'time_taken': float (hug_timer)}

قد يتم الوصول إلى التوجيهات عبر وسيطة مع بادئة hug_ ، أو باستخدام التعليقات التوضيحية من نوع Python 3. هذا الأخير هو النهج الأكثر حداثة ، ويوصى به. يمكن الوصول إلى التوجيهات التي تم الإعلان عنها في وحدة نمطية باستخدام اسمها المؤهل تمامًا كتعليق توضيحي (على سبيل المثال: module.directive_name ).

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

إضافة توجيهاتك الخاصة مباشرة إلى الأمام:

 @hug.directive () def square (value = 1 ، ** kwargs): '' '' 'تم تمريرها في المعلمة مضروبة بنفسها' '' قيمة return *[email protected] ()@hug.local () def tester ( القيمة: مربع = 10): إرجاع Valuetester () == 100

من أجل الاكتمال ، إليك مثال على الوصول إلى التوجيه عبر نهج الاسم السحري:

 @hug.directive () def multiply (value = 1 ، ** kwargs): '' '' 'تم تمريرها في المعلمة مضروبة بنفسها' '' value *[email protected] ()@hug.local () def tester ( Hug_multiply = 10): return hug_multiplytester () == 100

ينسق الإخراج وظيفة تأخذ إخراج وظيفة واجهة برمجة التطبيقات وتنسيقها للنقل إلى مستخدم واجهة برمجة التطبيقات.

 @hug.default_output_format () def my_output_formatter (data): إرجاع "السلسلة: {0}". format (data)@hug.get (output = hug.output_format.json) def hello (): return {'hello': ' عالم'}

كما هو موضح ، يمكنك تغيير تنسيق الإخراج بسهولة لكل من واجهة برمجة التطبيقات بأكملها بالإضافة إلى مكالمة API الفردية

الإدخال ينسق وظيفة تأخذ مجموعة البيانات المعطاة من مستخدم واجهة برمجة التطبيقات الخاصة بك وتنسيقها للتعامل معها.

 @hug.default_input_format ("application/json") def my_input_formatter (data): return ('Results' ، Hug.input_format.json (data))

يتم تعيين تنسيقات الإدخال بناءً على content_type من بيانات الطلب ، وأداء التحليل الأساسي فقط. يجب إجراء المزيد من التحليل التفصيلي من خلال التعليقات التوضيحية الموجودة على api_function

وظائف الوسيطة التي يتم استدعاؤها لكل طلب عمليات واجهة برمجة تطبيقات عناق

 @hug.request_middleware () def process_data (طلب ، استجابة): طلب. 'قيمة')

يمكنك أيضًا إضافة أي وسيط على نمط الصقر باستخدام:

 __hug __.

يمكن استخدام تعيين المعلمة لتجاوز أسماء المعلمات المستخلصة ، على سبيل المثال. للكلمات الرئيسية المحجوزة:

 استيراد marshmallow.fields كحقول [email protected] ('/foo' ، map_params = {'from': 'from_date'}). إرجاع find_foo (من _date)

يتم تعيين تنسيقات الإدخال بناءً على content_type من بيانات الطلب ، وأداء التحليل الأساسي فقط. يجب إجراء المزيد من التحليل التفصيلي من خلال التعليقات التوضيحية الموجودة على api_function

تقسيم واجهات برمجة التطبيقات على ملفات متعددة

يمكّنك Hug من تنظيم مشاريع كبيرة بأي طريقة تراها مناسبة. يمكنك استيراد أي وحدة نمطية تحتوي على وظائف مزخرفة عناق (معالجة الطلب ، والتوجيهات ، والمعالجات النوع ، وما إلى ذلك) وتمديد واجهة برمجة التطبيقات الأساسية الخاصة بك مع تلك الوحدة.

على سبيل المثال:

something.py

 استيراد [email protected] ('/') def say_hi (): العودة "مرحبا من شيء"

يمكن استيرادها إلى ملف API الرئيسي:

__init__.py

 استيراد Hugfrom. استيراد [email protected] ('/') def say_hi (): إرجاع "مرحبا من الجذر"@hug.extend_api ('/شيء')

أو بدلاً من ذلك - لحالات كهذه - حيث يتم تضمين وحدة واحدة فقط لكل عنوان URL:

 #بدلاً من ذلك

تكوين عناق 404

بشكل افتراضي ، يقوم Hug بإرجاع مواصفات API التي تم إنشاؤها تلقائيًا عندما يحاول المستخدم الوصول إلى نقطة نهاية لم يتم تعريفها. إذا كنت لا ترغب في إرجاع هذه المواصفات ، فيمكنك إيقاف توثيق 404:

من تطبيق سطر الأوامر:

 Hug -nd -f {file} #nd flag يخبر Hug بعدم إنشاء وثائق في 404

بالإضافة إلى ذلك ، يمكنك بسهولة إنشاء معالج 404 مخصصًا باستخدام hug.not_found Decorator:

 @hug.not_found () def not_found_handler (): إرجاع "لم يتم العثور عليه"

يعمل هذا الديكور بنفس الطريقة التي يعمل بها Decorators Hug HTTP ، وحتى على إدراك النسخة:

 @hug.not_found (إصدارات = 1) def not_found_handler (): return ""@hug.not_found (reports = 2) def not_found_handler (): return "not found"

دعم Asyncio

عند استخدام Decorator get و cli على Coroutines ، سيقوم Hug بجدولة تنفيذ Coroutine.

باستخدام ديكور Asyncio Coroutine

 @hug.get ()@asyncio.coroutined hello_world (): return "Hello"

باستخدام الكلمة الرئيسية Python 3.5 Async.

 @hug.get () async def hello_world (): return "Hello"

ملاحظة: Hug يعمل على Top Falcon وهو خادم غير متزامن. حتى إذا كان استخدام Asyncio ، فستظل الطلبات تتم معالجتها بشكل متزامن.

باستخدام Docker

إذا كنت ترغب في التطوير في Docker والحفاظ على نظافة نظامك ، فيمكنك القيام بذلك ولكن ستحتاج أولاً إلى تثبيت Docker.

بمجرد القيام بذلك ، ستحتاج إلى cd في دليل docker وتشغيل خادم الويب (Gunicorn) المحدد في ./docker/gunicorn/Dockerfile آلة المضيف.

 $ cd. Linux: $ ifconfig docker0 | جريب "inet" | CUT -D: -F2 | awk '{print $ 1}' | رأس -n1

بشكل افتراضي ، IP هو 172.17.0.1. على افتراض أن هذا هو IP الذي تراه ، أيضًا ، ستذهب بعد ذلك إلى http://172.17.0.1:8000/ في متصفحك لعرض واجهة برمجة التطبيقات الخاصة بك.

يمكنك أيضًا تسجيل الدخول إلى حاوية Docker التي يمكنك التفكير في مساحة عملك. تحتوي مساحة العمل هذه على Python و PIP مثبتة حتى تتمكن من استخدام هذه الأدوات داخل Docker. إذا كنت بحاجة إلى اختبار واجهة CLI ، على سبيل المثال ، ستستخدم هذا.

 $ Docker-Cormpose Run Workspace Bash

على حاوية workspace Docker الخاصة بك ، يتم /src ./docker/templates . يتم تحديد هذا ضمن services > app ./docker/docker-compose.yml .

 Bash-4.3# CD /SRC
Bash-4.3# Tree.├ __init__.py
└ المعالجات
    ├ عيد ميلاد
    └ hello.py

دليل واحد ، 3 ملفات

معلومات الاتصال الأمنية

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

للإبلاغ عن ثغرة أمنية ، يرجى استخدام جهة اتصال Tidelift Security. سوف Tidelift تنسيق الإصلاح والكشف.

لماذا عناق؟

العناق ببساطة يرمز إلى دليل مفيد. يمثل هذا هدف المشروع لمساعدة المطورين على إنشاء واجهات برمجة التطبيقات المكتوبة والبديهية.

شكرا وآمل أن تجد هذا العناق مفيدًا وأنت تقوم بتطوير واجهة برمجة تطبيقات Python التالية!

~ تيموثي كروسلي

يوسع
معلومات إضافية
تطبيقات ذات صلة
نوصي لك
أخبار ذات صلة الكل