`microdot` — 최소 HTTP 프레임워크#

Microdot은 MicroPython을 위한 작고 Flask에서 영감을 받은 HTTP 프레임워크입니다. asyncio 위에서 동작하며, 스레드 없이 여러 개의 동시 클라이언트를 처리하고, 익숙한 라우트 데코레이터 API를 제공합니다. 최소한의 애플리케이션은 다음과 같습니다:

from microdot import Microdot

app = Microdot()

@app.route('/')
async def index(request):
    return 'Hello, world!'

app.run(host='0.0.0.0', port=80)

class Microdot#

class microdot.Microdot#

HTTP 애플리케이션 인스턴스입니다. 스크립트 상단 근처에서 인스턴스 하나를 생성하고 라우트 핸들러로 데코레이트합니다. run()을 호출하거나 start_server()를 await하면 서빙이 시작됩니다.

라우트 등록

route(url_pattern: str, methods: list | None = None) → Callable#

나열된 HTTP 메서드(기본값 ['GET'])에 대해 url_pattern의 핸들러를 등록하는 데코레이터입니다. 함수에 적용되면 그 함수를 핸들러로 등록하고 함수를 변경 없이 반환하는 데코레이터를 반환합니다.

url_pattern: 경로 패턴입니다. 정적 세그먼트(/users)와 < / >로 둘러싼 동적 세그먼트를 지원합니다. 동적 세그먼트는 :로 구분되는 선택적 타입 접두사를 받습니다 – <int:id>, <path:rest>, <re:[0-9a-f]+:hex>. 기본 타입은 string입니다.
methods: HTTP 메서드 이름의 리스트입니다. 생략하면 GET만 매칭됩니다.

핸들러는 먼저 요청 객체와 함께 호출되고, 그다음 캡처된 동적 세그먼트들이 키워드 인자로 전달됩니다. 핸들러의 반환값이 HTTP 응답이 됩니다: Response, 문자열, 튜플 (body, status_code[, headers]), 또는 dict / list(JSON으로 전송됨).

get(url_pattern: str) → Callable#: route(url_pattern, methods=['GET'])의 편의 별칭 – 데코레이트된 함수를 url_pattern의 GET 핸들러로 등록합니다. 데코레이터를 반환합니다.

post(url_pattern: str) → Callable#: route(url_pattern, methods=['POST'])의 편의 별칭 – 데코레이트된 함수를 url_pattern의 POST 핸들러로 등록합니다. 데코레이터를 반환합니다.

put(url_pattern: str) → Callable#: route(url_pattern, methods=['PUT'])의 편의 별칭 – 데코레이트된 함수를 url_pattern의 PUT 핸들러로 등록합니다. 데코레이터를 반환합니다.

patch(url_pattern: str) → Callable#: route(url_pattern, methods=['PATCH'])의 편의 별칭 – 데코레이트된 함수를 url_pattern의 PATCH 핸들러로 등록합니다. 데코레이터를 반환합니다.

delete(url_pattern: str) → Callable#: route(url_pattern, methods=['DELETE'])의 편의 별칭 – 데코레이트된 함수를 url_pattern의 DELETE 핸들러로 등록합니다. 데코레이터를 반환합니다.

라이프사이클 훅

before_request(f: Callable) → Callable#: 모든 요청 전에 실행되도록 f 를 등록하는 데코레이터입니다. f 는 요청 객체를 인수로 받으며, 그 반환값은 일반적으로 무시됩니다. 요청을 단축 처리하려면 Response (또는 그것으로 변환되는 값)을 반환하십시오. 그러면 파이프라인의 나머지 부분은 건너뛰어지고 해당 응답이 전송됩니다. f 를 변경하지 않고 그대로 반환합니다.

after_request(f: Callable) → Callable#: 성공한 모든 요청 후에 실행되도록 f를 등록하는 데코레이터입니다. f는 (request, response)를 받으며 (수정되었을 수도 있는) 응답 객체를 반드시 반환해야 합니다. f를 변경 없이 반환합니다.

after_error_request(f: Callable) → Callable#: Microdot이 오류 응답(404, 500, 발생한 예외 등)을 생성한 후에 실행되도록 f를 등록하는 데코레이터입니다. f는 (request, response)를 받으며 (수정되었을 수도 있는) 응답 객체를 반드시 반환해야 합니다. f를 변경 없이 반환합니다.

errorhandler(status_code_or_exception_class) → Callable#: HTTP 상태 코드나 Python 예외 클래스에 대한 사용자 정의 핸들러를 등록하는 데코레이터입니다. 상태 코드의 경우 핸들러는 요청만 받고, 예외 클래스의 경우 (request, exception)을 받습니다. 데코레이터를 반환합니다.

마운트 및 중단

mount(subapp: Microdot, url_prefix: str = '', local: bool = False) → None#: 다른 Microdot 인스턴스의 라우트를 url_prefix 아래에 부착합니다. local이 False(기본값)이면 서브 앱의 before / after / error 핸들러도 부모에 부착됩니다. True이면 그 핸들러들은 서브 앱 라우트에 대해서만 실행됩니다. None을 반환합니다.

static abort(status_code: int, reason: str | None = None) → None#

주어진 상태 코드로 현재 요청을 중단하려면 HTTPException을 발생시키십시오. 정상적으로 반환하지 않습니다 – 프레임워크가 예외를 잡아 해당하는 오류 응답으로 변환합니다. 라우트 본문 내부에서 편리하게 사용할 수 있습니다:

from microdot import abort

@app.get('/users/<int:id>')
def get_user(request, id):
    user = lookup(id)
    if user is None:
        abort(404)
    return user.to_dict()

서버 실행

run(host: str = '0.0.0.0', port: int = 5000, debug: bool = False, ssl=None) → None#

호출 스레드를 블록하고 start_server()에 대해 asyncio.run()을 실행합니다. shutdown()이 호출되어 수신 루프가 종료된 후에만 None을 반환합니다. 독립 실행형 앱을 시작하는 가장 간단한 방법입니다:

app.run(host='0.0.0.0', port=80)

async start_server(host: str = '0.0.0.0', port: int = 5000, debug: bool = False, ssl=None, start_serving: bool = True) → None#

서버를 코루틴으로 시작합니다. 다른 작업들과 함께 기존 asyncio 이벤트 루프에 통합할 때 사용하십시오. 이 코루틴은 shutdown()이 호출될 때까지 반환하지 않습니다:

async def main():
    await asyncio.gather(
        app.start_server(port=80),
        capture_loop(),
    )

host: 수신할 네트워크 인터페이스입니다. '0.0.0.0'(기본값)은 모든 인터페이스를 의미하고, '127.0.0.1'은 루프백만을 의미합니다.
port: 수신할 TCP 포트입니다. 기본값 5000 – 평문 HTTP에는 80, HTTPS에는 443을 선택하십시오.
debug: True이면 모든 요청을 로깅하고 트레이스백을 stdout으로 덤프합니다.
ssl: 들어오는 연결을 TLS로 감싸기 위한 ssl.SSLContext 입니다. None (기본값)은 일반 HTTP를 의미합니다.
start_serving: CPython에서만 관련이 있습니다. MicroPython에서는 무시됩니다.

shutdown() → None#: 서버의 정상적인 종료(graceful shutdown)를 요청합니다. 라우트 핸들러에서 호출해도 안전합니다 – 루프가 종료되기 전에 현재 요청이 완료됩니다. 즉시 반환하며, 실제 종료는 진행 중인 요청이 끝난 후에 일어납니다.

속성

url_map: list#: 등록된 라우트들의 리스트로, (methods, URLPattern, handler, url_prefix, subapp) 튜플 형태입니다.

before_request_handlers: list#: before_request()로 등록된 호출 가능 객체들의 리스트로, 등록 순서대로입니다. 각각은 라우트 핸들러 전에 요청 객체와 함께 실행됩니다. 리스트를 직접 변경해도 동작하지만 거의 필요하지 않습니다 – 데코레이터를 사용하는 것이 좋습니다.

after_request_handlers: list#: after_request()로 등록된 호출 가능 객체들의 리스트로, 등록 순서대로입니다. 각각은 성공한 요청 후에 (request, response)와 함께 실행되며 (수정되었을 수도 있는) 응답을 반드시 반환해야 합니다.

after_error_request_handlers: list#: after_error_request()로 등록된 호출 가능 객체들의 리스트로, 등록 순서대로입니다. 각각은 (프레임워크 또는 애플리케이션 오류 핸들러에 의해) 오류 응답이 생성된 후에 (request, response)와 함께 실행되며 응답을 반드시 반환해야 합니다.

error_handlers: dict#: errorhandler()에 의해 채워지는, 오류 키에서 핸들러 호출 가능 객체로의 매핑입니다. 키는 HTTP 상태 코드(int) 또는 Python 예외 클래스이고, 값은 등록된 핸들러입니다. 상태 코드 핸들러는 (request)를 받고, 예외 클래스 핸들러는 (request, exception)을 받습니다.

debug: bool#: 서버가 debug=True로 실행 중인 동안 True입니다.

class Request#

class microdot.Request#

들어오는 HTTP 요청입니다. 인스턴스는 첫 번째 위치 인자로 라우트 핸들러에 전달됩니다. 애플리케이션이 Request를 직접 생성하지는 않습니다.

클래스 속성

max_content_length: int#: Content-Length가 이 바이트 수를 초과하는 요청을 413 응답으로 거부합니다. 기본값 16 KB.

max_body_length: int#: 메모리에 버퍼링되어 body를 통해 노출되는 가장 큰 본문입니다. 더 큰 본문(max_content_length까지)은 소켓에 남아 있으며 stream을 통해 읽어야 합니다. 기본값 16 KB.

max_readline: int#: 단일 요청 라인 / 헤더 라인의 최대 길이(바이트)입니다. 기본값 2 KB.

인스턴스 속성

app: Microdot#: 요청을 처리하는 Microdot 인스턴스입니다.

client_addr: tuple#: 클라이언트의 주소로 (host, port) 형태입니다.

method: str#: HTTP 메서드 문자열('GET', 'POST', …)입니다.

scheme: str#: 'http' 또는 'https'입니다.

url: str#: 전체 요청 URL 경로와 쿼리 문자열(호스트 이후의 모든 것)입니다.

path: str#: 경로 부분만입니다.

query_string: str | None#: 원시 쿼리 문자열 부분, 또는 None입니다.

args: MultiDict#: MultiDict로 파싱된 쿼리 문자열입니다.

headers: NoCaseDict#: 대소문자를 구분하지 않고 조회하는 NoCaseDict 형태의 요청 헤더입니다.

cookies: dict#: dict로 파싱된 Cookie 헤더입니다.

content_length: int#: 정수 Content-Length 값, 또는 없으면 0입니다.

content_type: str | None#: Content-Type 헤더 값, 또는 None입니다.

g: object#: 요청별 자유 형식 컨테이너(빈 객체)입니다. 여기에 속성을 할당하여 훅과 핸들러 사이에서 값을 전달하십시오(request.g.user = ...).

route: Callable#: 이 요청과 매칭된 핸들러 함수입니다.

url_prefix: str#: 라우트가 마운트된 접두사, 또는 ''입니다.

subapp: Microdot | None#: 마운트된 서브 앱 인스턴스, 또는 None입니다.

본문 접근

body: bytes#: bytes 형태의 전체 요청 본문입니다. 본문이 스트리밍 중일 때는 비어 있습니다(stream 참조).

stream: object#: 본문에 대한 read()를 노출하는 비동기 스트림 객체입니다. max_body_length보다 큰 본문에 이것을 사용하십시오.

json: dict | list | str | int | float | bool | None#: JSON으로 파싱된 본문(dict, list, str, int, float, 또는 bool – 페이로드가 인코딩하는 것이라면 무엇이든)이거나, Content-Type이 application/json이 아니면 None입니다.

form: MultiDict | None#: MultiDict로 된 URL 인코딩 폼 필드, 또는 None입니다. multipart/form-data의 경우 라우트를 microdot.multipart.with_form_data()로 데코레이트하십시오.

files: dict | None#: {name: FileUpload} 형태의 업로드된 파일들로, microdot.multipart.with_form_data()에 의해 채워집니다. 해당 데코레이터가 실행되기 전까지는 None입니다.

after_request(f: Callable) → Callable#: 요청 로컬 after-request 훅을 등록합니다 – 애플리케이션 수준의 after-request 핸들러 이후에, 성공한 경우에만 실행됩니다. f는 (request, response)를 받으며 (수정되었을 수도 있는) 응답 객체를 반드시 반환해야 합니다. f를 변경 없이 반환합니다.

class Response#

class microdot.Response(body=b'', status_code: int = 200, headers: dict | None = None, reason: str | None = None)#

HTTP 응답입니다. 대부분의 핸들러는 Microdot이 자동으로 Response로 변환하는 값을 반환합니다. 사용자 정의 헤더나 특정 상태 코드가 필요할 때 직접 생성하십시오.

body: 응답 본문입니다. str은 UTF-8로 인코딩되고, dict / list는 JSON으로 인코딩되며 그에 맞게 Content-Type이 설정됩니다. bytes는 그대로 전송되고, 파일류 객체나 비동기 제너레이터는 스트리밍됩니다.
status_code: 숫자 HTTP 상태입니다. 기본값 200.
headers: 응답 헤더의 dict(대소문자 구분 없음)입니다.
reason: 사용자 정의 이유 문구입니다. 200에 대해서는 "OK"로, 그 외에는 "N/A"로 기본 설정됩니다.

클래스 속성

default_content_type: str#: 명시적으로 설정되지 않았을 때 사용되는 Content-Type입니다. 기본값 'text/plain'.

default_send_file_max_age: int | None#: max_age 가 지정되지 않았을 때 send_file() 에 사용되는 Cache-Control: max-age 값입니다. None (기본값)은 Cache-Control 헤더가 없음을 의미합니다.

send_file_buffer_size: int#: send_file() 스트리밍의 청크 크기입니다. 기본값 1024.

already_handled: None#: 응답을 이미 직접 작성한 핸들러에서 반환되는 센티넬입니다(WebSocket 업그레이드에서 사용됨). 항상 None이며, 중요한 것은 그 동일성(identity)입니다.

types_map: dict#: send_file()이 콘텐츠 타입 추론에 사용하는 확장자-MIME 타입 맵입니다. css, gif, html, jpg, js, json, png, txt, svg를 매핑합니다.

메서드

set_cookie(cookie: str, value: str, path: str | None = None, domain: str | None = None, expires=None, max_age: int | None = None, secure: bool = False, http_only: bool = False, partitioned: bool = False) → None#: Set-Cookie 헤더를 추가합니다. expires는 미리 포맷된 문자열이거나 timetuple()을 가진 datetime류 객체일 수 있습니다. None을 반환하며, 헤더는 이 응답에 제자리에서 추가됩니다.

delete_cookie(cookie: str, **kwargs) → None#: 주어진 쿠키를 즉시 만료시키는 Set-Cookie를 설정합니다. kwargs는 set_cookie()와 동일한 옵션(path, domain, secure, http_only, partitioned)을 받습니다. expires와 max_age는 무시됩니다. None을 반환하며, 헤더는 이 응답에 제자리에서 추가됩니다.

classmethod redirect(location: str, status_code: int = 302) → Response#

리디렉션 응답을 반환합니다:

@app.get('/old')
def old(request):
    return Response.redirect('/new')

classmethod send_file(filename: str, status_code: int = 200, content_type: str | None = None, stream=None, max_age: int | None = None, compressed: bool | str = False, file_extension: str = '') → Response#: 파일시스템의 파일을 응답 본문으로 스트리밍합니다. content_type은 주어지지 않으면 types_map을 통해 확장자로부터 추론됩니다. compressed=True는 Content-Encoding: gzip을 설정합니다(파일은 이미 압축되어 있어야 합니다).

경고
filename은 직접 열립니다. 살균(sanitize)되지 않은 사용자 제공 경로를 절대 전달하지 마십시오 – 그렇게 하면 임의 파일 노출이 허용됩니다.

예외#

exception microdot.HTTPException#

abort()에 의해 발생하여 특정 상태 코드로 요청을 단락(short-circuit)합니다. Microdot이 이것을 잡아 해당하는 오류 응답으로 변환합니다.

status_code: int#: 반환할 숫자 HTTP 상태 코드 – abort()에 전달된 값입니다.

reason: str#: 오류 응답에 포함할 이유 문구입니다. abort()에 주어지지 않으면 "<status_code> error"(예: "404 error")로 기본 설정됩니다.

class URLPattern#

class microdot.URLPattern(url_pattern: str)#

라우트의 URL 패턴을 컴파일한 형태입니다. Microdot.route()에 의해 자동으로 생성되며, 애플리케이션이 직접 인스턴스화하는 경우는 드뭅니다.

classmethod register_type(type_name: str, pattern: str = '[^/]+', parser: Callable | None = None) → None#

라우트 패턴에서 사용할 새 동적 세그먼트 타입을 등록합니다. None을 반환하며, 타입은 클래스 수준 타입 레지스트리에 추가됩니다. 예를 들어 <uuid:...> 타입을 추가하려면:

URLPattern.register_type('uuid', '[0-9a-f-]{36}')

parser는 캡처된 문자열이 핸들러에 도달하기 전에 변환하는 선택적 호출 가능 객체입니다.

match(path: str) → dict | None#: path를 패턴에 대해 매칭하고 캡처된 그룹의 dict를 반환하거나, 매칭되지 않으면 None을 반환합니다.

헬퍼 클래스#

class microdot.MultiDict(initial_dict: dict | None = None)#

키당 여러 값을 저장하는 dict 서브클래스입니다. 같은 키가 두 번 이상 나타날 수 있는 쿼리 문자열과 URL 인코딩 폼 본문(?tag=a&tag=b)에 사용됩니다.

get(key, default=None, type: Callable | None = None)#: key에 대한 첫 번째 값을 반환하며, 선택적으로 type(호출 가능 객체)으로 변환합니다. 키가 없거나 변환이 실패하면 default를 반환하고, 그렇지 않으면 (선택적으로 변환된) 값을 반환합니다.

getlist(key, type: Callable | None = None) → list#: key에 대한 모든 값을 리스트로 반환하며, 선택적으로 각 값을 type으로 변환합니다. key가 없으면 빈 리스트를 반환합니다.

class microdot.NoCaseDict#: 대소문자 구분 없는 문자열 키를 가진 dict 서브클래스입니다. Request.headers와 Response.headers에 사용됩니다.

모듈 수준 함수#

microdot.abort(status_code: int, reason: str | None = None) → None#: Microdot.abort()의 단축입니다. 정상적으로 반환하지 않습니다 – HTTPException을 발생시킵니다. from microdot import abort로 임포트할 수 있습니다.

microdot.redirect(location: str, status_code: int = 302) → Response#: Response.redirect()의 단축입니다. from microdot import redirect로 임포트할 수 있습니다.

microdot.send_file(filename: str, **kwargs) → Response#: Response.send_file()의 단축입니다.

microdot.urlencode(s: str) → str#: URL 구성 요소를 퍼센트 인코딩합니다. URL에서 예약된 의미를 갖는 문자들(/, ?, &, =, #, 공백, …)을 그 %xx 16진수 이스케이프로 대체하여 결과가 경로 세그먼트나 쿼리 값 안에 안전하게 들어갈 수 있도록 합니다. 인코딩된 str을 반환합니다.

microdot.urldecode(s: str) → str#: URL 구성 요소를 퍼센트 디코딩합니다 – urlencode()의 역연산입니다. %xx 이스케이프는 그것이 인코딩하는 바이트로 대체되고, +는 공백으로 변환됩니다(전통적인 쿼리 문자열 관례). 디코딩된 str을 반환합니다.

microdot — 최소 HTTP 프레임워크#

class Microdot#

class Request#

class Response#

예외#

class URLPattern#

헬퍼 클래스#

모듈 수준 함수#

서브모듈#

`microdot` — 최소 HTTP 프레임워크#