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 [email protected] （'/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
