hug
2.6.0
อ่านเอกสารล่าสุด - เรียกดูที่เก็บรหัส GitHub
Hug มีจุดมุ่งหมายเพื่อให้การพัฒนา APIs ที่ขับเคลื่อนด้วยงูหลามง่ายที่สุดเท่าที่จะเป็นไปได้ แต่ก็ไม่ง่ายกว่า เป็นผลให้การพัฒนา Python API ง่ายขึ้นอย่างมาก
วัตถุประสงค์การออกแบบของ Hug:
ทำให้การพัฒนา API ที่ขับเคลื่อนด้วยงูหลามเป็นคำจำกัดความที่เป็นลายลักษณ์อักษร
เฟรมเวิร์กควรส่งเสริมรหัสที่มีการจัดทำเอกสารด้วยตนเอง
มันควรจะเร็ว นักพัฒนาไม่ควรรู้สึกถึงความจำเป็นที่จะต้องมองไปที่อื่นด้วยเหตุผลด้านประสิทธิภาพ
การเขียนการทดสอบสำหรับ APIs ที่เขียนขึ้นมาบนสุดของการกอดควรเป็นเรื่องง่ายและใช้งานง่าย
เวทมนตร์ทำครั้งเดียวในกรอบ API นั้นดีกว่าการผลักดันปัญหาให้กับผู้ใช้ API Framework
เป็นพื้นฐานสำหรับ Python API รุ่นต่อไปโดยใช้เทคโนโลยีล่าสุด
อันเป็นผลมาจากเป้าหมายเหล่านี้ Hug คือ Python 3+ เท่านั้นและสร้างขึ้นจากห้องสมุด HTTP ที่มีประสิทธิภาพสูงของ Falcon
รับการสนับสนุนอย่างมืออาชีพด้วยการสมัครสมาชิก TideLift
การสนับสนุนอย่างมืออาชีพสำหรับการกอดมีให้บริการเป็นส่วนหนึ่งของการสมัครสมาชิก TideLift TideLift ให้ทีมพัฒนาซอฟต์แวร์เป็นแหล่งเดียวสำหรับการจัดซื้อและบำรุงรักษาซอฟต์แวร์ด้วยการรับรองระดับมืออาชีพจากผู้เชี่ยวชาญที่รู้ดีที่สุดในขณะที่รวมเข้ากับเครื่องมือที่มีอยู่อย่างราบรื่น
การติดตั้งกอดนั้นง่ายเหมือน:
Pip3 ติดตั้ง HUG -การอัพเกรด
ในอุดมคติภายในสภาพแวดล้อมเสมือนจริง
สร้างตัวอย่าง API ด้วยจุดสิ้นสุดที่เรียบง่ายในไม่กี่บรรทัด
# filename: happy_birthday.py "" "พื้นฐาน (ฟังก์ชั่นเดียว) API เขียนโดยใช้ hug" "นำเข้า [email protected] ('/happy_birthday') def happy_birthday (ชื่อ, อายุ: hug.types.number = 1): "" "สุขสันต์วันเกิดให้กับผู้ใช้" "" return "สุขสันต์วันเกิด {อายุ} {ชื่อ}!". รูปแบบ (** ท้องถิ่น ())
ในการเรียกใช้จากประเภทบรรทัดคำสั่ง:
กอด -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-common-holiday -Greetings/) "" "Greetings =" Happy "ถ้า Event ==" Christmas ": Greetings =" Merry "ถ้า Event ==" Kwanzaa ": Greetings =" Joyous "ถ้า Event ==" Wishes ": Greetings =" Warm Warm "return" {greetings} {event}! ". format (** locals ())ซึ่งเมื่อคุณใช้งานเซิร์ฟเวอร์ดังกล่าวข้างต้นคุณสามารถใช้วิธีนี้:
curl http://localhost:8000/greet/wishes "Warm wishes!"
# filename: versioning_example.py "" "ตัวอย่างง่ายๆของการโทร hug api ด้วยเวอร์ชัน" "" นำเข้า [email protected] ('/echo', เวอร์ชัน = 1) def echo (ข้อความ): return [email protected] ('/echo', เวอร์ชัน = ช่วง (2, 5)) def echo (ข้อความ): return "echo: {text}". รูปแบบ (** locals ())
เพื่อเรียกใช้ตัวอย่าง:
hug -f versioning_example.py
จากนั้นคุณสามารถเข้าถึงตัวอย่างจาก localhost:8000/v1/echo?text=Hi / localhost:8000/v2/echo?text=Hi หรือเข้าถึงเอกสารสำหรับ API ของคุณจาก localhost:8000
หมายเหตุ: การกำหนดเวอร์ชันใน HUG จะรองรับทั้งส่วนหัวของเวอร์ชันและข้อมูลจำเพาะ URL โดยตรงโดยอัตโนมัติ
นักตกแต่งวิธี http ของ Hug ไม่ได้ปรับเปลี่ยนฟังก์ชั่นดั้งเดิมของคุณ สิ่งนี้ทำให้การทดสอบ HUG APIs ง่ายเหมือนการทดสอบฟังก์ชั่น Python อื่น ๆ นอกจากนี้นี่หมายถึงการโต้ตอบกับฟังก์ชั่น API ของคุณในรหัส Python อื่น ๆ นั้นตรงไปตรงมาเช่นเดียวกับการเรียกใช้ฟังก์ชัน API เท่านั้น Hug ทำให้ง่ายต่อการทดสอบสแต็ค Python เต็มรูปแบบของ API ของคุณโดยใช้ hug.test Module:
นำเข้า Hugimport Happy_birthdayhug.test.get (happy_birthday, 'happy_birthday', {'name': 'timothy', 'อายุ': 25}) # ส่งคืนวัตถุตอบกลับ คุณสามารถใช้วัตถุ Response กลับนี้สำหรับการยืนยันการทดสอบ (ตรวจสอบ test_happy_birthday.py ):
def tests_happy_birthday (): response = hug.test.get (happy_birthday, 'happy_birthday', {'ชื่อ': 'Timothy', 'อายุ': 25}) ยืนยันการตอบสนอง. Hug เปิดเผยวิธีเวทย์มนตร์ __hug_wsgi__ บนโมดูล API ทุกโมดูลโดยอัตโนมัติ การเรียกใช้ API ที่ใช้ HUG ของคุณบนเซิร์ฟเวอร์ WSGI มาตรฐานใด ๆ ควรจะง่ายพอ ๆ กับการชี้ไปที่ module_name : __hug_wsgi__
ตัวอย่างเช่น:
UWSGI-HTTP 0.0.0.0:8000-ตัวอย่างตัวอย่าง/hello_world.py-เรียกได้ __hug_wsgi__
เพื่อเรียกใช้ API ตัวอย่าง Hello World Hug
เมื่อสร้าง API โดยใช้กรอบการกอดคุณจะใช้แนวคิดต่อไปนี้:
วิธีการตกแต่ง get , post , update , ฯลฯ HTTP วิธีการตกแต่ง
@hug.get () # <- เป็นวิธีการ hug decoratordef hello_world (): return "hello"
Hug ใช้โครงสร้างของฟังก์ชั่นที่คุณตกแต่งเพื่อสร้างเอกสารสำหรับผู้ใช้ API ของคุณโดยอัตโนมัติ Hug ส่งผ่านคำขอการตอบสนองและตัวแปร API_VERSION เสมอไปยังฟังก์ชั่นของคุณหากพวกเขาถูกกำหนดพารามิเตอร์ในนิยามฟังก์ชั่นของคุณ
พิมพ์ฟังก์ชั่ นคำอธิบายประกอบที่เป็นทางเลือกที่แนบมากับอาร์กิวเมนต์วิธีการของคุณเพื่อระบุวิธีการตรวจสอบความถูกต้องของอาร์กิวเมนต์และแปลงเป็นประเภทหลาม
@hug.get () def math (number_1: int, number_2: int): #the: int หลังจากอาร์กิวเมนต์ทั้งสองเป็นคำอธิบายประกอบประเภท number_1 + number_2
พิมพ์คำอธิบายประกอบยังป้อนเข้าสู่การสร้างเอกสารอัตโนมัติของ hug เพื่อให้ผู้ใช้ API ของคุณทราบว่าจะให้ข้อมูลใดบ้าง
ฟังก์ชั่ นคำสั่งที่ดำเนินการกับข้อมูลคำขอ / การตอบกลับตามการร้องขอเป็นอาร์กิวเมนต์ใน 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): '' 'ส่งคืนผ่านพารามิเตอร์คูณด้วยตัวเอง' 'ค่าคืนค่า *[email protected] ()@hug.local () def tester ( ค่า: square = 10): return valuetester () == 100
เพื่อความสมบูรณ์นี่คือตัวอย่างของการเข้าถึงคำสั่งผ่านแนวทางชื่อวิเศษ:
@hug.directive () def ทวีคูณ (value = 1, ** kwargs): '' 'ส่งคืนผ่านพารามิเตอร์คูณด้วยตัวเอง' 'ค่าคืน *[email protected] ()@hug.local () def tester ( hug_multiply = 10): return hug_multiplytester () == 100
Output Formatters ฟังก์ชั่นที่ใช้เอาต์พุตของฟังก์ชั่น API ของคุณและจัดรูปแบบสำหรับการขนส่งไปยังผู้ใช้ API
@hug.default_output_format () def my_output_formatter (data): return "string: {0}" รูปแบบ (data)@hug.get (output = hug.output_format.json) def hello (): return {'hello': ' โลก'}ดังที่แสดงคุณสามารถเปลี่ยนรูปแบบผลลัพธ์สำหรับทั้ง API ทั้งหมดรวมถึงการโทร API แต่ละรายการ
อินพุต Formatters ฟังก์ชั่นที่ใช้ข้อมูลที่ได้รับจากผู้ใช้ API ของคุณและจัดรูปแบบสำหรับการจัดการ
@hug.default_input_format ("แอปพลิเคชัน/json") def my_input_formatter (ข้อมูล): return ('ผลลัพธ์', hug.input_format.json (ข้อมูล)) Formatters อินพุตถูกแมปตาม content_type ของข้อมูลคำขอและทำการแยกวิเคราะห์ขั้นพื้นฐานเท่านั้น การแยกวิเคราะห์รายละเอียดเพิ่มเติมควรทำโดยคำอธิบายประกอบประเภทที่มีอยู่ใน api_function ของคุณ
ฟังก์ชั่น มิดเดิลแวร์ ที่ได้รับการเรียกร้องให้ทุกครั้งที่มีการร้องขอ API กระบวนการ API
@hug.request_middleware () def process_data (คำขอ, การตอบกลับ): request.env ['server_name'] = 'condange'@hug.response_middleware () def process_data (คำขอ, การตอบสนอง, ทรัพยากร): response.set_header (' myheader ', 'ค่า')นอกจากนี้คุณยังสามารถเพิ่มมิดเดิลแวร์สไตล์ Falcon ได้อย่างง่ายดายโดยใช้:
__hug __. http.add_middleware (MiddlewareObject ())
การแมปพารามิเตอร์ สามารถใช้เพื่อแทนที่ชื่อพารามิเตอร์ที่อนุมานได้เช่น สำหรับคำหลักที่สงวนไว้:
นำเข้า marshmallow.fields เป็นฟิลด์ [email protected] ('/foo', map_params = {'จาก': 'from_date'}) # api call ใช้ 'from'def get_foo_by_date (from_date: fields.datetime ()): ส่งคืน find_foo (from_date)
Formatters อินพุตถูกแมปตาม content_type ของข้อมูลคำขอและทำการแยกวิเคราะห์ขั้นพื้นฐานเท่านั้น การแยกวิเคราะห์รายละเอียดเพิ่มเติมควรทำโดยคำอธิบายประกอบประเภทที่มีอยู่ใน api_function ของคุณ
กอดช่วยให้คุณสามารถจัดระเบียบโครงการขนาดใหญ่ในลักษณะที่คุณเห็นว่าเหมาะสม คุณสามารถนำเข้าโมดูลใด ๆ ที่มีฟังก์ชั่นการตกแต่งของ HUG (การจัดการคำขอ, คำสั่ง, ตัวจัดการประเภท ฯลฯ ) และขยาย API ฐานของคุณด้วยโมดูลนั้น
ตัวอย่างเช่น:
something.py
นำเข้า [email protected] ('/') def say_hi (): return 'hello from something'
สามารถนำเข้าสู่ไฟล์ API หลัก:
__init__.py
นำเข้า Hugfrom นำเข้า [email protected] ('/') def say_hi (): return "hi from root"@hug.extend_api ('/something') def something_api (): return [บางสิ่ง]
หรืออีกทางเลือกหนึ่ง - สำหรับกรณีเช่นนี้ - มีเพียงโมดูลเดียวเท่านั้นที่รวมอยู่ในเส้นทาง URL:
#อีกทางเลือกหนึ่ง
โดยค่าเริ่มต้น Hug จะส่งคืนข้อมูลจำเพาะ API ที่สร้างขึ้นอัตโนมัติเมื่อผู้ใช้พยายามเข้าถึงจุดสิ้นสุดที่ไม่ได้กำหนดไว้ หากคุณไม่ต้องการส่งคืนข้อมูลจำเพาะนี้คุณสามารถปิดเอกสาร 404 ฉบับ:
จากแอปพลิเคชันบรรทัดคำสั่ง:
hug -nd -f {file} #nd Flag บอก Hug ไม่สร้างเอกสารใน 404 นอกจากนี้คุณสามารถสร้างตัวจัดการ 404 ที่กำหนดเองได้อย่างง่ายดายโดยใช้ hug.not_found Dorjectionator:
@hug.not_found () def not_found_handler (): return "ไม่พบ"
มัณฑนากรนี้ใช้งานได้ในลักษณะเดียวกับ HUG HTTP วิธีการตกแต่ง
@hug.not_found (เวอร์ชัน = 1) def not_found_handler (): return ""@hug.not_found (เวอร์ชัน = 2) def not_found_handler (): return "ไม่พบ"
เมื่อใช้งาน get and cli Method Decorator บน Coroutines Hug จะกำหนดเวลาการดำเนินการของ coroutine
ใช้ Asyncio Coroutine Decorator
@hug.get ()@asyncio.coroutinedef hello_world (): return "hello"
การใช้คำหลัก Python 3.5 Async
@hug.get () async def hello_world (): return "hello"
หมายเหตุ: Hug กำลังทำงานบน Falcon ด้านบนซึ่งไม่ใช่เซิร์ฟเวอร์แบบอะซิงโครนัส แม้ว่าจะใช้ asyncio คำขอจะยังคงดำเนินการแบบซิงโครนัส
หากคุณต้องการพัฒนาใน Docker และรักษาระบบของคุณให้สะอาดคุณสามารถทำได้ แต่คุณจะต้องติดตั้ง Docker Compose ก่อน
เมื่อคุณทำเสร็จแล้วคุณจะต้อง cd ลงในไดเรกทอรี docker และเรียกใช้เว็บเซิร์ฟเวอร์ (Gunicorn) ที่ระบุไว้ใน ./docker/gunicorn/Dockerfile docker/gunicorn/dockerfile หลังจากนั้นคุณสามารถดูตัวอย่าง API ของคุณในเบราว์เซอร์ของคุณ โฮสต์เครื่อง
$ cd ./docker# นี่จะเรียกใช้ Gunicorn บนพอร์ต 8000 ของคอนเทนเนอร์ Docker. $ docker-compose up gunicorn# จากเครื่องโฮสต์ค้นหาที่อยู่ IP ของคุณ Linux: $ ifconfig Docker0 | grep 'inet' | CUT -D: -F2 | awk '{พิมพ์ $ 1}' | หัว -N1 โดยค่าเริ่มต้น IP คือ 172.17.0.1 สมมติว่าเป็น IP ที่คุณเห็นเช่นกันคุณจะไปที่ http://172.17.0.1:8000/ ในเบราว์เซอร์ของคุณเพื่อดู API ของคุณ
นอกจากนี้คุณยังสามารถลงชื่อเข้าใช้คอนเทนเนอร์ Docker ที่คุณสามารถพิจารณาพื้นที่ทำงานของคุณ พื้นที่ทำงานนี้ติดตั้ง Python และ Pip เพื่อให้คุณสามารถใช้เครื่องมือเหล่านั้นภายใน Docker หากคุณต้องการทดสอบอินเทอร์เฟซ CLI เช่นคุณจะใช้สิ่งนี้
$ docker-compose run bash workspace bash
ในคอนเทนเนอร์ Docker workspace ของคุณไดเรกทอรี ./docker/templates บนคอมพิวเตอร์โฮสต์ของคุณติดตั้ง /src ในคอนเทนเนอร์ Docker สิ่งนี้ถูกระบุภายใต้ services > app ของ ./docker/docker-compose.yml
bash-4.3# cd /src
bash-4.3# tree.├── __init__.py
└── Handlers
├──วันเกิดปี่
└──สวัสดีปี่
1 ไดเรกทอรี 3 ไฟล์กอดให้ความสำคัญกับความปลอดภัยและคุณภาพอย่างจริงจัง การมุ่งเน้นนี้เป็นเหตุผลว่าทำไมเราถึงพึ่งพาส่วนประกอบที่ผ่านการทดสอบอย่างละเอียดและใช้เครื่องมือการวิเคราะห์แบบคงที่ (เช่นโจรและความปลอดภัย) เพื่อตรวจสอบความปลอดภัยของฐานรหัสของเรา หากคุณพบหรือพบปัญหาด้านความปลอดภัยที่อาจเกิดขึ้นโปรดแจ้งให้เราทราบได้ทันทีเพื่อให้เราสามารถแก้ไขได้
หากต้องการรายงานช่องโหว่ด้านความปลอดภัยโปรดใช้ผู้ติดต่อ TideLift Security TideLift จะประสานงานการแก้ไขและการเปิดเผย
กอดเพียงแค่คำแนะนำที่เป็นประโยชน์หวังว่า สิ่งนี้แสดงให้เห็นถึงเป้าหมายของโครงการเพื่อช่วยแนะนำนักพัฒนาในการสร้าง API ที่เขียนได้ดีและใช้งานง่าย
ขอบคุณและฉันหวังว่าคุณจะพบว่าการกอด นี้ มีประโยชน์เมื่อคุณพัฒนา Python API ครั้งต่อไป!
~ Timothy Crosley
