hug
2.6.0
최신 설명서 읽기 - GitHub 코드 저장소 찾아보기
Hug는 Python Driven API를 최대한 간단하게 만들지 만 간단하지는 않습니다. 결과적으로 Python API 개발을 크게 단순화합니다.
Hug의 디자인 목표 :
Python Driven API를 서면 정의로 간결하게 개발하십시오.
프레임 워크는 해당 자체 신호를 강조해야합니다.
빠르야합니다. 개발자는 성능의 이유로 다른 곳을 볼 필요성을 느끼지 않아야합니다.
포옹 위에 작성된 API에 대한 테스트 작성은 쉽고 직관적이어야합니다.
API 프레임 워크에서 한 번만 한 마술은 API 프레임 워크 사용자에게 설정된 문제를 추진하는 것보다 낫습니다.
최신 기술을 수용하여 차세대 Python API의 기초가 되십시오.
이러한 목표의 결과로, Hug는 Python 3+ 전용이며 Falcon의 고성능 HTTP 라이브러리를 기반으로합니다.
TideLift 구독으로 전문적으로 지원하는 포옹을 받으십시오
Hug에 대한 전문 지원은 TideLift 구독의 일부로 제공됩니다. TideLift는 소프트웨어 개발 팀에게 소프트웨어를 구매하고 유지 관리 할 수있는 단일 소스를 제공하며, 기존 도구와 완벽하게 통합하면서 가장 잘 아는 전문가의 전문가 등급 보증을 제공합니다.
포옹 설치는 다음과 같이 간단합니다.
PIP3 설치 -Upgrade
이상적으로는 가상 환경 내에서.
단순한 줄로 간단한 엔드 포인트가있는 예제 API를 구축하십시오.
# filename : happy_birthday.py "" "" "" "" "" "import [email protected] ( '/happy_birthday') def happy_birthday (이름, 나이 : hug.types.number = 1) : "" "생일 축하합니다.
명령 줄 유형에서 실행하려면 :
포옹 -f happy_birthday.py
Browser에서 예제에 액세스 할 수 있습니다. localhost:8000/happy_birthday?name=hug&age=1 . 그런 다음 localhost:8000/documentation 에서 API 문서를 확인하십시오.
매개 변수는 URL에서 인코딩 할 수도 있습니다 (전체 예제는 happy_birthday.py 를 확인하십시오).
@hug.get ( '/greet/{event}') def greet (event : str) : "" "" ""http://blog.ketchum.com/how-to-write-10-common-holiday -Greetings/) "" "Greetings ="Happy "이벤트 ="크리스마스 ":"크리스마스 ": greetings ="메리 "이벤트 =="kwanzaa ": greetings ="즐거움 "이벤트 =="소원 ": greetings ="warm "return"{greetings} {event}! ". 형식 (** locals ())위와 같이 서버를 실행하면 다음과 같은 방식으로 사용할 수 있습니다.
curl http://localhost:8000/greet/wishes "Warm wishes!"
# filename : versioning_example.py "" "버전이있는 Hug API 호출의 간단한 예" "" "import [email protected] ( '/echo', versions = 1) def echo (텍스트) : return [email protected]. ( '/echo', 버전 = 범위 (2, 5)) def echo (텍스트) : "echo : {text}". 형식 (** locals ())
예제를 실행하려면 :
hug -f versioning_example.py
그런 다음 localhost:8000/v1/echo?text=Hi / localhost:8000/v2/echo?text=Hi 또는 localhost:8000 의 문서에 액세스 할 수 있습니다.
참고 : HUG 버전화는 버전 헤더와 직접 URL 기반 사양을 자동으로 지원합니다.
Hug의 http 방법 데코레이터는 원래 기능을 수정하지 않습니다. 이로 인해 테스트 포옹 API가 다른 Python 기능을 테스트하는 것만 큼 간단하게 만듭니다. 또한 이는 다른 Python 코드에서 API 기능과 상호 작용하는 것이 Python 전용 API 기능을 호출하는 것만 큼 간단합니다. Hug는 hug.test 모듈을 사용하여 API의 전체 파이썬 스택을 쉽게 테스트 할 수 있습니다.
hugimport 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 (haphy_birthday, 'happy_birthday', { 'name': 'timothy', 'age': 25}) asstatus.status == http_200assert response.data는 없음 Hug는 모든 API 모듈에 자동으로 __hug_wsgi__ 매직 메소드를 노출시킵니다. 모든 표준 WSGI 서버에서 Hug 기반 API를 실행하는 것은 module_name 을 포인트하는 것만 큼 간단해야합니다. __hug_wsgi__ .
예를 들어:
uwsgi-http 0.0.0.0:8000 -wsgi-file examples/hello_world.py-통화 가능한 __hug_wsgi__
Hello World Hug 예제 API를 실행하려면.
Hug Framework를 사용하여 API를 구축 할 때는 다음 개념을 사용합니다.
메소드 데코레이터는 get 메서드 update 변경 post 않고 API로 파이썬 기능을 노출시키는 HTTP 메소드 데코레이터
@hug.get () # <- Hug Method DecoratorDef Hello_world () : "Hello"를 반환합니다.
Hug는 장식 한 기능의 구조를 사용하여 API 사용자를위한 문서를 자동으로 생성합니다. Hug는 기능 정의에서 매개 변수가 정의 된 경우 항상 요청, 응답 및 API_Version 변수를 기능에 전달합니다.
유형 주석 화는 선택적으로 메소드 인수에 첨부되어 인수가 파이썬 유형으로 검증되고 변환되는 방법을 지정하기 위해 인수에 첨부됩니다.
@hug.get () def math (number_1 : int, number_2 : int) : #the : int at aind ad
유형 주석은 또한 API 사용자에게 공급 할 데이터를 알 수 있도록 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) : '' '는 매개 변수로 전달 된 반품 자체로 전달 된 반품' '[email protected] ()@hug.local () def 테스터 ( 값 : square = 10) : return valuetester () == 100
완전성을 위해 여기에 마법 이름 접근법을 통해 지침에 액세스하는 예입니다.
@hug.directive () def multiply (value = 1, ** kwargs) :`` ''는 매개 변수로 전달 된 반품 자체로 전달 된 반품 ''[email protected] ()@hug.local () def treder ( hug_multiply = 10) : hug_multiplytester () == 100을 반환합니다
출력은 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 통화 모두에 대한 출력 형식을 쉽게 변경할 수 있습니다.
입력은 API 사용자로부터 제공되는 데이터 본문을 가져와 처리를 위해 형식화하는 함수를 형성합니다 .
@hug.default_input_format ( "application/json") def my_input_formatter (data) : return ( 'results', hug.input_format.json (data)).
입력 형태는 요청 데이터의 content_type 에 따라 매핑되며 기본 구문 분석 만 수행합니다. api_function 에 존재하는 유형 주석으로보다 자세한 구문 분석을 수행해야합니다.
모든 요청에 요청을받는 미들웨어 기능 Hug API 프로세스
@hug.request_middleware () def process_data (요청, 응답) : request.env [ 'server_name'] = 'change'@hug.response_middleware () def process_data (요청, 응답, 리소스) : response.set_header ('myheader ', '값')다음을 사용하여 Falcon 스타일 미들웨어를 쉽게 추가 할 수도 있습니다.
__HUG __. http.add_middleware (middlewareObject ())
매개 변수 매핑을 사용하여 추론 된 매개 변수 이름을 무시할 수 있습니다. 예약 키워드 :
import Marshmallow.fields as Fields [email protected] ( '/foo', map_params = { 'from': 'from_date'}) # api 호출을 사용합니다. return find_foo (from_date)
입력 형태는 요청 데이터의 content_type 에 따라 매핑되며 기본 구문 분석 만 수행합니다. api_function 에 존재하는 유형 주석으로보다 자세한 구문 분석을 수행해야합니다.
Hug를 사용하면 적합한 방식으로 대규모 프로젝트를 구성 할 수 있습니다. Hug Decorated 기능 (요청 처리, 지침, 유형 처리기 등)이 포함 된 모든 모듈을 가져 와서 해당 모듈로 기본 API를 확장 할 수 있습니다.
예를 들어:
something.py
import [email protected] ( '/') def say_hi () : 'hello yours athant'
기본 API 파일로 가져올 수 있습니다.
__init__.py
Hugfrom의 가져 오기. 가져 오기@hug.get ( '/') def say_hi () : "hi from root"@hug.extend_api ( '/something') def something_api () : return [something]
또는 또는 이와 같은 경우 - URL 경로에 따라 하나의 모듈 만 포함되는 경우 :
#onatialItlyHug.api (__ name __). Extend (무언가, '/something')
기본적으로 Hug는 사용자가 정의되지 않은 엔드 포인트에 액세스하려고 할 때 자동 생성 된 API 사양을 반환합니다. 이 사양을 반환하지 않으려면 404 문서를 끄질 수 있습니다.
명령 줄 응용 프로그램에서 :
hug -nd -f {file} #nd 플래그는 Hug에게 404에 문서를 생성하지 말라고 지시합니다. 또한 hug.not_found Decorator를 사용하여 사용자 정의 404 핸들러를 쉽게 만들 수 있습니다.
@hug.not_found () def not_found_handler () : "찾기 없음"리턴
이 데코레이터는 Hug 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 데코레이터 사용
@hug.get ()@asyncio.coroutineef hello_world () : "hello"를 반환합니다.
Python 3.5 Async 키워드 사용.
@hug.get () async def hello_world () : return "hello"
참고 : Hug는 비동기 서버가 아닌 최상위 Falcon에서 실행 중입니다. Asyncio를 사용하더라도 요청은 여전히 동기식으로 처리됩니다.
Docker에서 개발하고 시스템을 깨끗하게 유지하려면 그렇게 할 수 있지만 먼저 Docker Compose를 설치해야합니다.
이 작업을 마치면 docker 디렉토리에 CD를 cd 로 사용하여 ./docker/gunicorn/Dockerfile 에 지정된 웹 서버 (Gunicorn)를 실행해야하며, 그 후 브라우저에서 API의 출력을 미리 볼 수 있습니다. 호스트 머신.
$ cd ./docker# 이것은 Docker 컨테이너의 포트 8000에서 Gunicorn을 실행합니다. $ docker-com-compy up gunicorn# host host machine에서 windows & mac 용# : $ docker-machine ip default# for aff. Linux : $ ifconfig docker0 | grep 'inet'| 컷 -d : -f2 | awk '{print $ 1}'| 헤드 -n1 기본적으로 IP는 172.17.0.1입니다. 그것이 당신이 보는 IP라고 가정하면, 당신은 브라우저에서 http://172.17.0.1:8000/ 로 이동하여 API를 보게됩니다.
작업 공간을 고려할 수있는 Docker 컨테이너에 로그인 할 수도 있습니다. 이 작업 공간에는 파이썬과 PIP가 설치되어있어 Docker 내에서 해당 도구를 사용할 수 있습니다. 예를 들어 CLI 인터페이스를 테스트 해야하는 경우이를 사용합니다.
$ docker-compose run 작업 공간 bash
Docker workspace 컨테이너에서 호스트 컴퓨터의 ./docker/templates 디렉토리는 Docker 컨테이너에서 /src 에 장착됩니다. 이것은 ./docker/docker-compose.yml 의 services > app 에 지정됩니다.
Bash-4.3# CD /SRC
bash-4.3# tree. ─ __init__.py
Handlers
➢ 생일 .py
Hello.py
1 디렉토리, 3 파일포옹은 보안과 품질을 심각하게 받아들입니다. 이 초점은 철저한 테스트 구성 요소에만 의존하고 정적 분석 도구 (예 : 산적 및 안전)를 사용하여 코드 기반의 보안을 확인합니다. 잠재적 인 보안 문제를 찾거나 만나면 즉시 해결할 수 있도록 즉시 알려주십시오.
보안 취약점을보고하려면 TideLift 보안 연락처를 사용하십시오. Tidelift는 수정 및 공개를 조정합니다.
Hug는 단순히 희망적으로 유용한 가이드를 나타냅니다. 이는 개발자가 잘 쓰여지고 직관적 인 API를 만들도록 돕는 프로젝트의 목표를 나타냅니다.
감사합니다. 다음 Python API를 개발할 때이 포옹 이 도움이되기를 바랍니다.
~ 디모데 크로 슬리
