phew! Pico（或Python）HTTP端点管理器

:warning: 请注意！这是一个非常新的项目，最多只能算是alpha阶段。

专门为Pico W上的MicroPython设计的轻量级Web服务器和模板库。它旨在为创建高质量Web界面提供完整的工具包。

phew!非常适合创建使用Raspberry Pi Pico W的连接项目的基于Web的配置界面。

• phew!的功能
• 基本示例
• 功能参考
  • 服务器模块
    • add_route
    • set_catchall
    • run
  • 类型
    • 请求类型
    • 响应类型
      • 简写
  • 模板
    • render_template
    • 模板表达式
      • 变量
      • 条件显示
      • 包含
  • dns模块
    • run_catchall

phew!的功能

• 一个基本的Web服务器
• 优化速度（在import和执行期间）
• 最小化内存使用
• 参数化路由规则 /greet/<name>
• 模板引擎允许内联Python表达式 {{name.lower()}}
• GET，POST请求方法
• 查询字符串解码和解析
• 未路由请求的catchall处理程序
• multipart/form-data，x-www-form-urlencoded和JSON POST正文
• 基于字符串、字节或生成器的响应
• connect_to_wifi便利方法

在可能的情况下，phew!会尽量减少您（开发者）需要编写的代码和设置量，以选择合理的默认值并隐藏那些很少需要调整的细节。

基本示例

一个示例Web服务器，当请求时返回1到100之间的随机数（或可选地由调用者指定的范围）

from phew import server, connect_to_wifi

connect_to_wifi("<ssid>", "<password>")

@server.route("/random", methods=["GET"])
def random_number(request):
  import random
  min = int(request.query.get("min", 0))
  max = int(request.query.get("max", 100))
  return str(random.randint(min, max))

@server.catchall()
def catchall(request):
  return "Not found", 404

server.run()

phew专门设计为考虑性能和最小资源使用。通常这意味着它将优先考虑尽可能少的工作，包括假设传入请求的正确性。

---

功能参考

服务器模块

《server》模块提供了运行带有路由处理器的Web服务器的所有功能。

add_route

server.add_route(path, handler, methods=["GET"])

向路由表中添加一个新的路由。当接收到一个请求时，服务器会检查每个路由，以找到与请求路径和方法最匹配的最具体路由。如果找到路由，则使用包含有关请求详情的request参数调用handler函数。

def my_handler(request):
  return "I got it!", 200

server.add_route("/testpath", my_handler, methods=["GET"])

或者，也可以使用装饰器

@server.route("/testpath", methods=["GET"])
def my_handler(request):
  return "I got it!", 200

set_catchall

server.set_catchall(handler)

为未匹配到路由的请求提供一种捕获所有方法的机制。

def my_catchall(request):
  return "No matching route", 404

server.set_catchall(my_catchall)

或者，也可以使用装饰器

@server.set_catchall()
def my_catchall(request):
  return "No matching route", 404

run

server.run(host="0.0.0.0", port=80)

启动Web服务器并开始处理传入的请求。

server.run()

类型

请求

Request对象包含从传入请求中解析出来的所有信息，包括表单数据、查询字符串参数、HTTP方法、路径等。

提供给add_route和set_catchall的处理函数将接收一个Request对象作为它们的第一个参数。

成员	示例	类型	描述
协议	"HTTP/1.1"	字符串	协议版本
方法	"GET"或"POST"	字符串	用于此请求的HTTP方法
uri	"/path/to/page?parameter=foo"	字符串	请求的完整URI
路径	"/path/to/page"	字符串	URI中的路径部分
查询字符串	"parameter=foo"	字符串	URI中的查询字符串部分
表单	{"foo": "bar", "name": "geoff"}	字典	POST体解析为multipart/form-data
数据	[{"name": "jenny"}, {"name": "geoff"}]	任意	POST体解析为JSON
查询	{"parameter": "foo"}	字典	解析查询字符串的结果

当您的路由处理器被调用时，请求已经被完全解析，您可以访问与请求相关的任何属性（例如，对于multipart/form-data请求的form字典），任何无关的属性将被设置为None。

@server.add_route("/login", ["POST"])
def login_form(request):
  username = request.form.get("username", None)
  password = request.form.get("password", None)

  # check the user credentials with your own code
  # for example: 
  # 
  # logged_in = authenticate_user(username, password)

  if not logged_in:
    return "Username or password not recognised", 401

  return "Logged in!", 200

响应

Response对象封装了程序对传入请求的所有响应属性。这包括结果的HTTP状态码（例如，200 OK!），要返回的数据以及任何相关头信息。

处理函数可以显式创建并返回一个Response对象，或使用一些简写形式来避免编写样板代码。

成员	示例	类型	描述
状态	200	整数	HTTP状态码
头部	{"Content-Type": "text/html"}	字典	返回的头字典
主体	"这是响应主体"	字符串或生成器	要返回的内容

@server.add_route("/greeting/<name>", ["GET"])
def user_details(request):
  return Response(f"Hello, {name}", status=200, {"Content-Type": "text/html"})

简写

作为简写，处理函数也可以返回一个包含一到三个值的tuple

• 主体 - 字符串或生成器方法
• 状态码 - 如果未提供，则默认为200
• 头部 - 如果未提供，则默认为{"Content-Type": "text/html"}

例如

@server.add_route("/greeting/<name>", ["GET"])
def user_details(request, name):
  return f"Hello, {name}", 200

模板

没有要提供的内容的Web服务器没有什么用处。虽然提供文件内容或生成JSON内容很简单，但当我们想向用户展示动态生成的网页时，事情就变得复杂了。

phew!提供了一个模板引擎，允许您编写普通的HTML，并嵌入Python代码片段来输出变量值、解析输入或动态加载资源。

render_template

render_template(template, param1="foo", param2="bar", ...):

render_template方法接受文件系统上模板文件的路径和一组命名参数，这些参数将在解析时传递到模板中。

此方法是一个生成器，可以分块生成解析结果，最小化存储结果所需的内存量，因为可以直接流式传输，而不是首先将整个结果构建为字符串。

通常，您将在处理方法中调用 render_template 以创建 Response 的主体。

模板表达式

如果您无法将这些动态数据注入到模板中，模板就没什么用处。使用 phew!，您可以在解析时嵌入 Python 表达式，格式为 {{<expression here>}}。

变量

在 simplest 形式中，您可以通过将值放在双大括号中将其嵌入。您还可以使用任何内置的 Python 方法执行更复杂的转换。

  <div id="name">{{name}}</div>

  <div id="name">{{name.upper()}}</div>
  
  <div id="name">{{"/".join(name.split(" "))}}</div>

条件显示

如果您只想在满足某些条件时显示一个值，则可以使用 Python 的三元运算符（稍显笨拙）。

<div>
  You won
  {{"1st" if prize == 1 else ""}}
  {{"2nd" if prize == 2 else ""}}
  {{"3rd" if prize == 3 else ""}}
  prize!
</div>

或

<div>
  You won
  {{["1st", "2nd", "3rd"][prize]}}
  prize!
</div>

虽然有点笨拙，但这种做法是可行的。另一种选择是在处理方法中选中适当的值，并将其作为参数传递到模板中，但这意味着您的一些文本将嵌入到 Python 代码中，而不是在模板文件的一个位置中。

包含

您可以在外层模板中再次调用 render_template() 以包含另一个模板。

include.html

Hello there {{name}}!

main.html

<!DOCTYPE html>
<body>
  {{render_template("include.html", name=name)}}
</body>

:warning: 注意：您需要显式传递模板参数到包含的模板 - 默认情况下它们不可用。

dns模块

为了简化设备配置接口（通过 captive portal）的实现，phew! 提供了一个捕获所有 DNS 请求的 DNS 服务器。

如果您将 Pico W 设置为接入点模式并运行捕获所有 DNS 请求的 DNS 服务器，它将将所有 DNS 请求路由回本地设备，以便进行处理。

run_catchall

dns.run_catchall(ip_address)

一旦接入点模式，请传入您的设备 IP 地址。