microdot --- framework HTTP tối giản

Microdot là một framework HTTP nhỏ gọn, lấy cảm hứng từ Flask, dành cho MicroPython. Nó chạy trên nền asyncio, xử lý nhiều client đồng thời mà không cần luồng, và cung cấp API route-decorator quen thuộc. Một ứng dụng tối giản trông như sau:

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

Một phiên bản ứng dụng HTTP. Một phiên bản được khởi tạo gần đầu tập lệnh và được trang trí với các trình xử lý route; gọi run() hoặc await start_server() để bắt đầu phục vụ.

Đăng ký route

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

Decorator đăng ký một trình xử lý cho url_pattern theo các phương thức HTTP được liệt kê (mặc định ['GET']). Trả về decorator mà khi áp dụng cho một hàm, đăng ký hàm đó làm trình xử lý và trả về hàm không thay đổi.

url_pattern

Mẫu đường dẫn. Hỗ trợ các đoạn tĩnh (/users) và các đoạn động được bao trong < / >. Các đoạn động chấp nhận tiền tố kiểu tùy chọn được phân tách bằng : -- <int:id>, <path:rest>, <re:[0-9a-f]+:hex>. Kiểu mặc định là string.

methods

Danh sách các tên phương thức HTTP. Nếu bỏ qua, chỉ GET được khớp.

Trình xử lý được gọi với đối tượng request đầu tiên, sau đó là bất kỳ đoạn động nào được bắt giữ dưới dạng đối số từ khóa. Giá trị trả về của trình xử lý trở thành phản hồi HTTP: một Response, một chuỗi, một tuple (body, status_code[, headers]), hoặc một dict / list (gửi dưới dạng JSON).

get(url_pattern: str) → Callable

Bí danh tiện lợi cho route(url_pattern, methods=['GET']) -- đăng ký hàm được trang trí làm trình xử lý GET cho url_pattern. Trả về decorator.

post(url_pattern: str) → Callable

Bí danh tiện lợi cho route(url_pattern, methods=['POST']) -- đăng ký hàm được trang trí làm trình xử lý POST cho url_pattern. Trả về decorator.

put(url_pattern: str) → Callable

Bí danh tiện lợi cho route(url_pattern, methods=['PUT']) -- đăng ký hàm được trang trí làm trình xử lý PUT cho url_pattern. Trả về decorator.

patch(url_pattern: str) → Callable

Bí danh tiện lợi cho route(url_pattern, methods=['PATCH']) -- đăng ký hàm được trang trí làm trình xử lý PATCH cho url_pattern. Trả về decorator.

delete(url_pattern: str) → Callable

Bí danh tiện lợi cho route(url_pattern, methods=['DELETE']) -- đăng ký hàm được trang trí làm trình xử lý DELETE cho url_pattern. Trả về decorator.

Hook vòng đời

before_request(f: Callable) → Callable

Decorator đăng ký f để chạy trước mỗi request. f nhận đối tượng request; giá trị trả về của nó thường bị bỏ qua. Để bỏ qua request, trả về một Response (hoặc một giá trị chuyển đổi thành một) -- phần còn lại của pipeline sẽ bị bỏ qua và phản hồi đó được gửi. Trả về f không thay đổi.

after_request(f: Callable) → Callable

Decorator đăng ký f để chạy sau mỗi request thành công. f nhận (request, response) và phải trả về đối tượng phản hồi (có thể đã được sửa đổi). Trả về f không thay đổi.

after_error_request(f: Callable) → Callable

Decorator đăng ký f để chạy sau khi Microdot tạo ra phản hồi lỗi (404, 500, ngoại lệ được ném, v.v.). f nhận (request, response) và phải trả về đối tượng phản hồi (có thể đã được sửa đổi). Trả về f không thay đổi.

errorhandler(status_code_or_exception_class) → Callable

Decorator đăng ký một trình xử lý tùy chỉnh cho một mã trạng thái HTTP hoặc một lớp ngoại lệ Python. Đối với mã trạng thái, trình xử lý chỉ nhận request; đối với các lớp ngoại lệ, nhận (request, exception). Trả về decorator.

Gắn kết và hủy bỏ

mount(subapp: Microdot, url_prefix: str = '', local: bool = False) → None

Đính kèm các route của một phiên bản Microdot khác dưới url_prefix. Khi local là False (mặc định), các trình xử lý before/after/error của ứng dụng con cũng được đính kèm vào ứng dụng cha. Khi True, các trình xử lý đó chỉ chạy cho các route của ứng dụng con. Trả về None.

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

Ném HTTPException để hủy bỏ request hiện tại với mã trạng thái đã cho. Không bao giờ trả về bình thường -- framework bắt ngoại lệ và chuyển nó thành phản hồi lỗi tương ứng. Tiện lợi bên trong thân route:

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()

Chạy máy chủ

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

Chặn luồng gọi, chạy asyncio.run() trên start_server(). Trả về None chỉ sau khi shutdown() được gọi và vòng lặp lắng nghe thoát. Cách đơn giản nhất để khởi chạy một ứng dụng độc lập:

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

Khởi động máy chủ dưới dạng coroutine. Sử dụng cái này khi tích hợp với một vòng lặp sự kiện asyncio hiện có cùng với các tác vụ khác. Coroutine không trả về cho đến khi shutdown() được gọi:

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

Giao diện mạng để lắng nghe. '0.0.0.0' (mặc định) có nghĩa là tất cả giao diện; '127.0.0.1' có nghĩa là chỉ loopback.

port

Cổng TCP để lắng nghe. Mặc định 5000 -- chọn 80 cho HTTP thuần, 443 cho HTTPS.

debug

Nếu True, ghi nhật ký mỗi request và xuất tracebacks ra stdout.

ssl

Một ssl.SSLContext để bọc các kết nối đến trong TLS. None (mặc định) có nghĩa là HTTP thuần.

start_serving

Chỉ liên quan trên CPython; bị bỏ qua trên MicroPython.

shutdown() → None

Yêu cầu tắt máy chủ một cách duyên dáng. An toàn để gọi từ một trình xử lý route -- request hiện tại hoàn thành trước khi vòng lặp thoát. Trả về ngay lập tức; việc tắt thực tế xảy ra sau khi request đang xử lý hoàn thành.

Thuộc tính

url_map: list

Danh sách các route đã đăng ký dưới dạng các tuple (methods, URLPattern, handler, url_prefix, subapp).

before_request_handlers: list

Danh sách các callable được đăng ký với before_request(), theo thứ tự đăng ký. Mỗi cái chạy với đối tượng request trước trình xử lý route. Thay đổi trực tiếp danh sách có tác dụng nhưng hiếm khi cần -- ưu tiên decorator.

after_request_handlers: list

Danh sách các callable được đăng ký với after_request(), theo thứ tự đăng ký. Mỗi cái chạy với (request, response) sau một request thành công và phải trả về phản hồi (có thể đã được sửa đổi).

after_error_request_handlers: list

Danh sách các callable được đăng ký với after_error_request(), theo thứ tự đăng ký. Mỗi cái chạy với (request, response) sau khi một phản hồi lỗi được tạo ra (bởi framework hoặc bởi trình xử lý lỗi ứng dụng) và phải trả về phản hồi.

error_handlers: dict

Ánh xạ các khóa lỗi tới các callable trình xử lý, được điền bởi errorhandler(). Khóa là mã trạng thái HTTP (int) hoặc các lớp ngoại lệ Python; giá trị là các trình xử lý đã đăng ký. Trình xử lý mã trạng thái nhận (request); trình xử lý lớp ngoại lệ nhận (request, exception).

debug: bool

True trong khi máy chủ đang chạy với debug=True.

class Request

class microdot.Request

Một HTTP request đến. Các phiên bản được truyền vào các trình xử lý route như đối số vị trí đầu tiên. Ứng dụng không xây dựng Request trực tiếp.

Thuộc tính lớp

max_content_length: int

Từ chối các request có Content-Length vượt quá số byte này với phản hồi 413. Mặc định 16 KB.

max_body_length: int

Phần thân lớn nhất được đệm vào bộ nhớ và hiển thị qua body. Các phần thân lớn hơn (lên đến max_content_length) vẫn trên socket và phải được đọc qua stream. Mặc định 16 KB.

max_readline: int

Độ dài tối đa của một dòng request / dòng header tính bằng byte. Mặc định 2 KB.

Thuộc tính phiên bản

app: Microdot

Phiên bản Microdot đang xử lý request.

client_addr: tuple

Địa chỉ của client dưới dạng (host, port).

method: str

Chuỗi phương thức HTTP ('GET', 'POST', ...).

scheme: str

'http' hoặc 'https'.

url: str

Đường dẫn URL đầy đủ của request và chuỗi truy vấn (mọi thứ sau host).

path: str

Chỉ phần đường dẫn.

query_string: str | None

Phần chuỗi truy vấn thô, hoặc None.

args: MultiDict

Chuỗi truy vấn đã được phân tích cú pháp dưới dạng MultiDict.

headers: NoCaseDict

Header request dưới dạng NoCaseDict (tra cứu không phân biệt chữ hoa/thường).

cookies: dict

Header Cookie đã được phân tích cú pháp dưới dạng dict.

content_length: int

Giá trị Content-Length nguyên, hoặc 0 nếu không có.

content_type: str | None

Giá trị header Content-Type, hoặc None.

g: object

Một container tự do theo từng request (một đối tượng trần). Gán thuộc tính cho nó để truyền giá trị giữa các hook và trình xử lý (request.g.user = ...).

route: Callable

Hàm trình xử lý khớp với request này.

url_prefix: str

Tiền tố mà route được gắn vào, hoặc ''.

subapp: Microdot | None

Phiên bản ứng dụng con được gắn kết, hoặc None.

Truy cập phần thân

body: bytes

Phần thân request đầy đủ dưới dạng bytes. Trống khi phần thân đang được stream (xem stream).

stream: object

Một đối tượng stream bất đồng bộ hiển thị read() trên phần thân. Sử dụng cái này cho các phần thân lớn hơn max_body_length.

json: dict | list | str | int | float | bool | None

Phần thân được phân tích cú pháp dưới dạng JSON (một dict, list, str, int, float, hoặc bool -- bất kể payload mã hóa), hoặc None nếu Content-Type không phải là application/json.

form: MultiDict | None

Các trường biểu mẫu được mã hóa URL dưới dạng MultiDict, hoặc None. Đối với multipart/form-data, trang trí route với microdot.multipart.with_form_data().

files: dict | None

Các file tải lên dưới dạng {name: FileUpload}, được điền bởi microdot.multipart.with_form_data(). None cho đến khi decorator đó chạy.

after_request(f: Callable) → Callable

Đăng ký một hook after-request cục bộ theo request -- chạy sau các trình xử lý after-request cấp ứng dụng, chỉ khi thành công. f nhận (request, response) và phải trả về đối tượng phản hồi (có thể đã được sửa đổi). Trả về f không thay đổi.

class Response

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

Một phản hồi HTTP. Hầu hết các trình xử lý trả về các giá trị mà Microdot chuyển đổi tự động thành Response; xây dựng một cái trực tiếp khi bạn cần các header tùy chỉnh hoặc mã trạng thái cụ thể.

body

Phần thân phản hồi. str được mã hóa UTF-8; dict / list được mã hóa JSON và Content-Type được đặt tương ứng; bytes được gửi nguyên dạng; đối tượng tương tự file hoặc async generator thực hiện streaming.

status_code

Mã trạng thái HTTP số. Mặc định 200.

headers

Dict của các header phản hồi (không phân biệt chữ hoa/thường).

reason

Cụm từ lý do tùy chỉnh. Mặc định là "OK" cho 200 và "N/A" cho các trường hợp khác.

Thuộc tính lớp

default_content_type: str

Content-Type được sử dụng khi không có cái nào được đặt rõ ràng. Mặc định 'text/plain'.

default_send_file_max_age: int | None

Giá trị Cache-Control: max-age cho send_file() khi max_age không được cung cấp. None (mặc định) có nghĩa là không có header Cache-Control.

send_file_buffer_size: int

Kích thước chunk cho streaming send_file(). Mặc định 1024.

already_handled: None

Sentinel được trả về từ các trình xử lý đã ghi phản hồi trực tiếp (được sử dụng bởi các nâng cấp WebSocket). Luôn là None; danh tính là điều quan trọng.

types_map: dict

Bản đồ phần mở rộng sang kiểu mime được sử dụng bởi send_file() để suy luận kiểu nội dung. Ánh xạ css, gif, html, jpg, js, json, png, txt, svg.

Phương thức

Thêm một header Set-Cookie. expires có thể là một chuỗi đã được định dạng sẵn hoặc một đối tượng tương tự datetime với timetuple(). Trả về None; header được thêm vào phản hồi này tại chỗ.

Đặt Set-Cookie hết hạn ngay lập tức cookie đã cho. kwargs chấp nhận cùng các tùy chọn như set_cookie() (path, domain, secure, http_only, partitioned); expires và max_age bị bỏ qua. Trả về None; header được thêm vào phản hồi này tại chỗ.

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

Trả về một phản hồi chuyển hướng:

@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

Stream một file từ filesystem làm phần thân phản hồi. content_type được suy luận từ phần mở rộng qua types_map nếu không được cung cấp. compressed=True đặt Content-Encoding: gzip (file phải đã được nén).

Cảnh báo

filename được mở trực tiếp. Không bao giờ truyền một đường dẫn do người dùng cung cấp chưa được làm sạch -- làm như vậy cho phép tiết lộ file tùy ý.

Ngoại lệ

exception microdot.HTTPException

Được ném bởi abort() để hủy bỏ một request với mã trạng thái cụ thể. Microdot bắt cái này và chuyển nó thành phản hồi lỗi tương ứng.

status_code: int

Mã trạng thái HTTP số để trả về -- giá trị được truyền vào abort().

reason: str

Cụm từ lý do để bao gồm trong phản hồi lỗi. Nếu không được cung cấp cho abort(), mặc định là "<status_code> error" (ví dụ "404 error").

class URLPattern

class microdot.URLPattern(url_pattern: str)

Dạng đã được biên dịch của mẫu URL của một route. Được xây dựng tự động bởi Microdot.route(); ứng dụng hiếm khi khởi tạo trực tiếp.

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

Đăng ký một kiểu đoạn động mới để sử dụng trong các mẫu route. Trả về None; kiểu được thêm vào registry kiểu cấp lớp. Ví dụ để thêm kiểu <uuid:...>

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

parser là một callable tùy chọn chuyển đổi chuỗi được bắt giữ trước khi nó đến trình xử lý.

match(path: str) → dict | None

Khớp path với mẫu và trả về một dict của các nhóm được bắt giữ, hoặc None khi không khớp.

Các lớp trợ giúp

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

Một lớp con dict lưu trữ nhiều giá trị cho mỗi khóa. Được sử dụng cho chuỗi truy vấn và phần thân biểu mẫu được mã hóa URL nơi cùng một khóa có thể xuất hiện nhiều hơn một lần (?tag=a&tag=b).

get(key, default=None, type: Callable | None = None)

Trả về giá trị đầu tiên cho key, tùy chọn được chuyển đổi với type (một callable). Trả về default nếu khóa bị thiếu hoặc chuyển đổi thất bại; ngược lại trả về giá trị (tùy chọn được chuyển đổi).

getlist(key, type: Callable | None = None) → list

Trả về tất cả các giá trị cho key dưới dạng list, tùy chọn với mỗi giá trị được chuyển đổi bởi type. Trả về list rỗng nếu key không có mặt.

class microdot.NoCaseDict

Một lớp con dict với các khóa chuỗi không phân biệt chữ hoa/thường. Được sử dụng cho Request.headers và Response.headers.

Hàm cấp module

microdot.abort(status_code: int, reason: str | None = None) → None

Lối tắt cho Microdot.abort(). Không bao giờ trả về bình thường -- ném HTTPException. Có thể nhập như from microdot import abort.

microdot.redirect(location: str, status_code: int = 302) → Response

Lối tắt cho Response.redirect(). Có thể nhập như from microdot import redirect.

microdot.send_file(filename: str, **kwargs) → Response

Lối tắt cho Response.send_file().

microdot.urlencode(s: str) → str

Mã hóa phần trăm một thành phần URL. Thay thế các ký tự có ý nghĩa dành riêng trong URL (/, ?, &, =, #, khoảng trắng, ...) bằng các escape hex %xx để kết quả có thể an toàn nằm bên trong một đoạn đường dẫn hoặc giá trị truy vấn. Trả về str đã được mã hóa.

microdot.urldecode(s: str) → str

Giải mã phần trăm một thành phần URL -- nghịch đảo của urlencode(). Các escape %xx được thay thế bằng byte chúng mã hóa, và + được chuyển đổi thành khoảng trắng (quy ước chuỗi truy vấn lịch sử). Trả về str đã được giải mã.

Các submodule