hug
2.6.0
閱讀最新文檔 - 瀏覽GitHub代碼存儲庫
擁抱的目的是使開發Python驅動的API盡可能簡單，但並不簡單。結果，它極大地簡化了Python API的開發。
擁抱的設計目標：
使開發Python驅動的API像書面定義一樣簡潔。
該框架應鼓勵代碼自我介紹。
它應該很快。出於績效原因，開發人員永遠不應感到需要在其他地方尋找其他地方。
在擁抱上寫下API的編寫測試應該簡單而直觀。
在API框架中，魔術曾經完成一次，比將問題設置為API框架的用戶要好。
成為下一代Python API的基礎，採用最新技術。
由於這些目標，擁抱僅是python 3+，並基於Falcon的高性能HTTP圖書館
通過Tidelift訂閱獲得專業支持的擁抱
作為Tidelift訂閱的一部分，可以提供對擁抱的專業支持。 Tidelift為軟件開發團隊提供了購買和維護其軟件的單一來源，並提供了最了解它的專家，同時與現有工具無縫集成。
安裝擁抱很簡單：
PIP3安裝擁抱 - 升級
理想情況下，在虛擬環境中。
僅在幾行中構建一個具有簡單端點的示例API。
＃文件名：happy_birthday.py“”“基本（單函數）使用hug”編寫的API“”“ import [email protected]（'/happhaph_birthday'）def happy_birthday（name，age，age ege：hug.types. number = 1） “”“給用戶生日快樂”，“返回“快樂{age}生日{name}！”。格式（** locals（））
從命令行類型運行：
擁抱-f happy_birthday.py
您可以在瀏覽器中訪問以下示例： localhost:8000/happy_birthday?name=hug&age=1 。然後在localhost:8000/documentation
參數也可以在URL中編碼（查看happy_birthday.py有關整個示例）。
@hug.get（'/ettry/{event}'）def ettry（event：str）：“”“迎接適當（摘自http://blog.ketchum.com/how-to-write-10-common-holiday -greetings/）“”“ engreting =“ happy”如果event ==“聖誕節”：engretings =“ herry”如果event ==“ kwanzaa”：engretings =“ joyous”如果event = = = =“ wishes”：engretings =“溫暖“返回” {engretings} {event}！”。格式（** locals（））一旦您運行服務器，您可以使用這種方式：
curl http://localhost:8000/greet/wishes "Warm wishes!"
＃文件名：versioning_example.py“”“一個簡單的hug api呼叫with ventersing”“”“ import [email protected]（'/echo'，echo'，versions = 1）def echo echo（text）：return text @hug.get （'/echo'，versions = range（2，5））def echo（text）：返回“ echo：{text}”。格式（** locals（））
運行示例：
擁抱-F版本ing_example.py
然後，您可以從localhost:8000/v1/echo?text=Hi / localhost:8000/v2/echo?text=Hi或從localhost:8000
注意：Hug中的版本控制自動支持版本標題和基於直接URL的規範。
擁抱的http方法裝飾器不會修改您的原始功能。這使得測試的擁抱API與測試任何其他Python功能一樣簡單。此外，這意味著在其他Python代碼中與您的API函數進行交互，就像調用Python僅API函數一樣直接。擁抱使使用hug.test模塊可以輕鬆測試API的完整python堆棧：
導入Hugimport Happy_birthdayHug.test.get（Happy_birthday，'Happy_birthday'，{'name'：'timothy'，'age'：25}）＃返迴響應對象您可以使用此Response對象進行測試斷言（請查看test_happy_birthday.py ）：
def tests_happy_birthday（）：wendesp = hug.test.get（happy_birthday，'happy_birthday'，{'name'：'timothy'：'timothy'，'age'：25}）castert assert wordss.status == http_200assert respession.data none none none none none none none擁抱在每個API模塊上自動公開__hug_wsgi__魔法。在任何標準WSGI服務器上運行基於擁抱的API應該與將其指向module_name ： __hug_wsgi__ __。
例如：
UWSGI-HTTP 0.0.0.0：8000 -wsgi-file示例/hello_world.py-可靠__hug_wsgi__
運行Hello World Hug示例API。
使用擁抱框架構建API時，您會使用以下概念：
方法裝飾器get ， post ， update等HTTP方法裝飾器，使您的Python功能作為API，同時保持Python方法不變
@hug.get（）＃< - 是擁抱方法decoratordef hello_world（）：返回“你好”
擁抱使用您裝飾的功能的結構，可以自動為API用戶生成文檔。如果在您的函數定義中定義了params，則擁抱總是將請求，響應和API_Version變量傳遞給您的函數。
類型註釋函數可選地附加到您的方法參數上，以指定參數的驗證並轉換為Python類型
@hug.get（）def Math（number_1：int，number_2：int）：＃the：int兩個參數之後是類型AnnotationRetrunturn number_1 + number_2
類型註釋還可以輸入hug的自動文檔生成，以使您的API的用戶知道要提供的數據。
指示功能可以根據請求 /響應數據執行的函數，該功能基於請求作為API_FUNCTION中的參數。這些僅應用於輸入參數，目前不能用作輸出格式或轉換。
@hug.get（）def test_time（hug_timer）：返回{'time_taken'：float（hug_timer）}可以通過使用hug_前綴的參數或使用Python 3類型註釋來訪問指令。後者是更現代的方法，建議使用。可以在模塊中使用其完全合格的名稱作為類型註釋（ex： module.directive_name ）訪問指令。
除了明顯的輸入轉換用例外，指令可用於將數據傳輸到您的API功能中，即使它們不存在於請求查詢字符串，郵政正文等中。有關如何以這種方式使用指令的示例請參見示例文件夾中的身份驗證示例。
添加您自己的指示很簡單：
@hug.directive（）def square（value = 1，** kwargs）：''''''以參數乘以本身乘以''''''''''''''''''' '''''[email protected]（）@hug.local（）def tester（）def tester（值：正方形= 10）：返回valuetester（）== 100
為了完整性，以下是通過魔術名稱方法訪問指令的示例：
@hug.directive（）def倍數（value = 1，** kwargs）：'''''''以參數乘以本身乘以'''''''''''''''''' ''''''''[email protected]（）@hug.local（）def tester（）def tester（ hug_multiply = 10）：返回hug_multiplytester（）== 100
輸出格式化一個功能，該函數將您的API功能輸出並格式化其以將其傳輸到API的用戶。
@hug.default_output_format（）def my_output_formatter（data）：返回“字符串：{0}”。格式（data）@hug.get（output = hug.output_format.json）def hello（）世界'}如圖所示，您可以輕鬆更改整個API的輸出格式以及單獨的API調用
輸入格式化一個函數，該函數獲取來自API用戶的數據主體並格式化用於處理。
@hug.default_input_format（“ application/json”）def my_input_formatter（data）：return（'結果'，hug.input_format.json（data））
基於請求數據的content_type映射輸入格式器，僅執行基本解析。應通過api_function上的類型註釋進行更詳細的解析
中間件功能被要求每個請求都被召集一個擁抱API進程
@hug.request_middleware（）def process_data（請求，響應）：request.env ['server_name'] ='change@@hug.response_middleware（）def process_data（請求，響應，資源）：wendment.set.set.set. header（'myheader'，'myheader'，，'，，'myheader'，，，'，， '價值'）
您也可以使用以下方式輕鬆添加任何獵鷹樣式中間件
__HUG __。http.add_middleware（MiddlewareObject（））
參數映射可用於覆蓋推斷參數名稱，例如。對於保留的關鍵字：
導入Marshmallow.fields作為字段[email protected]（'/foo'，map_params = {'from'：'：'from_date'}）＃api call use'from'def get_foo_by_date（from_date：farf_date：fields.datement （））：返回find_foo（from_date）
基於請求數據的content_type映射輸入格式器，僅執行基本解析。應通過api_function上的類型註釋進行更詳細的解析
擁抱使您能夠以任何合適的方式組織大型項目。您可以導入任何包含擁抱裝飾功能的模塊（請求處理，指令，類型處理程序等），並使用該模塊擴展基本API。
例如：
something.py
導入[email protected]（'/'）def say_hi（）：返回'你好
可以將其導入到主要API文件中：
__init__.py
進口擁抱。導入[email protected]（'/'）def say_hi（）：返回“ hi from”@hug.extend_api（'/something'）def sosity_api（）：返回[某物]
或者，對於此類情況 - 根據URL路線僅包含一個模塊：
＃替代hug.api（__名稱__）。擴展（某物，'/something'）
默認情況下，當用戶試圖訪問未定義的端點時，擁抱將返回自動生成的API規格。如果您不想返回此規範，則可以關閉404文檔：
從命令行應用程序：
擁抱-nd -f {file} #nd標誌告訴擁抱不要在404上生成文檔此外，您可以使用hug.not_found Decorator輕鬆創建一個自定義的404處理程序：
@hug.not_found（）def not_found_handler（）：返回“找不到”
該裝飾儀的工作方式與HTTP方法裝飾器相同，甚至意識到：
@hug.not_found（versions = 1）def not_found_handler（）：return“”@hug.not_found（versions = 2）def not_found_handler（）：返回“找不到”
在Coroutines上使用get和cli方法裝飾器時，Hug將安排執行Coroutine。
使用Asyncio Coroutine Decorator
@hug.get（）@asyncio.coroutinededef hello_world（）：返回“ hello”
使用Python 3.5異步關鍵字。
@hug.get（）async def hello_world（）：返回“ hello”
注意：擁抱在不是異步服務器的頂部獵鷹上運行。即使使用Asyncio，請求仍然會同步處理。
如果您想在Docker中開發並保持系統清潔，可以做到這一點，但是您需要先安裝Docker組成。
完成此操作後，您需要在./docker/gunicorn/Dockerfile中指定的docker cd並運行Web服務器（Gunicorn），然後您可以在瀏覽器上在瀏覽器中預覽API的輸出。主機機器。
$ cd ./docker#這將在Docker容器的端口8000上運行Gunicorn。 Linux：$ ifconfig docker0 | grep'inet'|剪切-d：-f2 |尷尬'{print $ 1}'|頭-N1默認情況下，IP為172.17.0.1。假設這也是您看到的IP，然後您將訪問http://172.17.0.1:8000/在瀏覽器中查看您的API。
您還可以登錄一個可以考慮工作空間的Docker容器。該工作區已安裝了Python和PIP，因此您可以在Docker中使用這些工具。例如，如果需要測試CLI接口，則將使用此操作。
$ Docker-Compose Run Workspace Bash
在您的Docker workspace容器上，主機計算機上的./docker/templates目錄已安裝在Docker容器中的/src上。這是在./docker/docker-compose.yml的services > app中指定的。
BASH-4.3＃CD /SRC
bash-4.3＃tree.├--__init__.py
└ - 赫勒人
├ - 生日
└ - ─hello.py
1個目錄，3個文件擁抱認真對待安全和質量。這個重點是為什麼我們僅依靠經過徹底測試的組件並利用靜態分析工具（例如強盜和安全）來驗證我們的代碼庫的安全性。如果您發現或遇到任何潛在的安全問題，請立即讓我們知道，以便我們解決這些問題。
要報告安全漏洞，請使用Tidelift安全聯繫人。 Tidelift將協調修復和披露。
擁抱只是代表希望有用的指南。這代表了該項目的目標，以幫助指導開發人員創建書面和直觀的API。
謝謝，我希望您在開發下一個Python API時會發現這個擁抱有所幫助！
〜Timothy Crosley
