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 헤더를 추가합니다. expires는 미리 포맷된 문자열이거나 timetuple()을 가진 datetime류 객체일 수 있습니다. 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을 반환합니다.

서브모듈