`pywebio.platform` — 应用部署¶

platform 模块为PyWebIO提供了在不同Web框架中运行PyWebIO应用的支持。

参见

Directory Deploy¶

可以使用 path_deploy() 或 path_deploy_http() 来从一个路径中部署PyWebIO应用。服务端会根据用户访问的URL来确定需要加载的文件并从中读取PyWebIO应用来运行。

用户无法访问该目录下以下划线开始的文件和目录。

pywebio.platform.path_deploy(base, port=0, host='', index=True, static_dir=None, reconnect_timeout=0, cdn=True, debug=True, allowed_origins=None, check_origin=None, max_payload_size='200M', **tornado_app_settings)[源代码]¶

从一个路径中部署PyWebIO应用

服务端使用WebSocket协议与浏览器进行通讯。

参数

base (str) – 用于加载PyWebIO应用的根目录
port (int) – 服务器监听的端口
host (str) – 服务绑定的地址
index (bool/callable) – 当请求一个文件夹时是否显示默认的索引页面，默认为 True 。 index 也可以为一个函数来自定义索引页面，其接收请求的文件夹路径作为参数，返回页面HTML字符串。你可以在文件夹中创建一个 index.py PyWebIO应用文件来重写文件夹的索引页。
static_dir (str) – 应用静态文件目录。目录下的文件可以通过 http://<host>:<port>/static/files 访问。例如 http_static_dir 路径下存在文件 A/B.jpg ，则其URL为 http://<host>:<port>/static/A/B.jpg。
reconnect_timeout (int) – 客户端重连超时时间(秒)。客户端若意外与服务端断开连接，在 reconnect_timeout 秒内可以重新连接并自动恢复会话。

剩余参数的详细说明见 pywebio.platform.tornado.start_server() 的同名参数。

pywebio.platform.path_deploy_http(base, port=0, host='', index=True, static_dir=None, cdn=True, debug=True, allowed_origins=None, check_origin=None, session_expire_seconds=None, session_cleanup_interval=None, max_payload_size='200M', **tornado_app_settings)[源代码]¶

从一个路径中部署PyWebIO应用

服务端使用HTTP协议与浏览器进行通讯。

关于 path_deploy_http() 的 base, port, host, index, static_dir 参数的详细说明见 pywebio.platform.path_deploy() 的同名参数。

剩余参数的详细说明见 pywebio.platform.tornado_http.start_server() 的同名参数。

Application Deploy¶

start_server() 函数可以启动一个Web服务器来将PyWebIO应用作为Web服务运行。

webio_handler() 和 webio_view() 函数用于将PyWebIO应用整合到现有的Python Web项目中。

wsgi_app() 和 asgi_app() 用于获取运行PyWebIO应用的 WSGI 或 ASGI app。很适合当你不想使用Web框架内置的server来启动服务的情况。比如，你想使用其他WSGI server来启动应用，或者你正在将应用部署到一些云环境中。目前仅在Flask、Django 和 FastApi后端中支持 wsgi_app() / asgi_app()

在 1.1 版更改: Added the cdn parameter in start_server(), webio_handler() and webio_view().

在 1.2 版更改: Added the static_dir parameter in start_server().

在 1.3 版更改: Added the wsgi_app() and asgi_app().

Tornado相关¶

服务端可以通过两种协议（WebSocket 和 HTTP）来与用户浏览器通信。

WebSocket¶

pywebio.platform.tornado.start_server(applications, port=0, host='', debug=False, cdn=True, static_dir=None, remote_access=False, reconnect_timeout=0, allowed_origins=None, check_origin=None, auto_open_webbrowser=False, max_payload_size='200M', **tornado_app_settings)[源代码]¶

启动一个 Tornado server 将PyWebIO应用作为Web服务提供。

Tornado server 使用WebSocket协议与浏览器进行通讯。

Tornado为PyWebIO应用的默认后端Server，可以直接使用 from pywebio import start_server 导入。

参数

applications (list/dict/callable) –
PyWebIO应用. 可以是任务函数或者任务函数的字典或列表。

类型为字典时，字典键为任务名，类型为列表时，函数名为任务名。

可以通过 app URL参数选择要运行的任务(例如访问 http://host:port/?app=foo 来运行 foo 任务)，默认使用运行 index 任务函数，当 index 任务不存在时，PyWebIO会提供一个默认的索引页作为主页。参见 Server模式

任务函数为协程函数时，使用基于协程的会话实现；任务函数为普通函数时，使用基于线程的会话实现。
port (int) – 服务监听的端口。设置为 0 时，表示自动选择可用端口。
host (str) – 服务绑定的地址。 host 可以是IP地址或者为hostname。如果为hostname，服务会监听所有与该hostname关联的IP地址。通过设置 host 为空字符串或 None 来将服务绑定到所有可用的地址上。
debug (bool) – 是否开启Tornado Server的debug模式，开启后，代码发生修改后服务器会自动重启。详情请参阅 tornado 文档
cdn (bool/str) – 是否从CDN加载前端静态资源，默认为 True 。支持传入自定义的URL来指定静态资源的部署地址
static_dir (str) – 应用静态文件目录。目录下的文件可以通过 http://<host>:<port>/static/files 访问。例如 http_static_dir 路径下存在文件 A/B.jpg ，则其URL为 http://<host>:<port>/static/A/B.jpg。
remote_access (bool/dict) –
是否开启远程接入的功能。开启后，你将得到一个你当前应用的临时公网访问地址，其他人可以通过此地址访问你的应用。使用远程接入可以很方便地将应用临时分享给其他人来体验。目前远程接入功能由 localhost.run 提供，你可以传入一个dict来配置远程接入服务，目前支持以下配置：
- ssh_key_path: 自定义ssh密钥的路径, 默认使用 ~/.ssh/id_xxx. 注意目前仅支持rsa 和 ed25519 类型的密钥。
- custom_domain: 使用自定义域名。这项功能需要localhost.run订阅版。参见： Custom Domains - localhost.run
auto_open_webbrowser (bool) – 当服务启动后，是否自动打开浏览器来访问服务。（该操作需要操作系统支持）
reconnect_timeout (int) – 客户端重连超时时间(秒)。客户端若意外与服务端断开连接，在 reconnect_timeout 秒内可以重新连接并自动恢复会话。
allowed_origins (list) –
除当前域名外，服务器还允许的请求的来源列表。来源包含协议、域名和端口部分，允许使用 Unix shell 风格的匹配模式:
- * 为通配符
- ? 匹配单个字符
- [seq] 匹配seq中的任何字符
- [!seq] 匹配任何不在seq中的字符
比如 https://*.example.com 、 *://*.example.com

全部规则参见 Python文档
check_origin (callable) – 请求来源检查函数。接收请求来源(包含协议、域名和端口部分)字符串作为参数，返回 True/False 指示服务器接受/拒绝该请求。若设置了 check_origin ， allowed_origins 参数将被忽略
auto_open_webbrowser – 当服务启动后，是否自动打开浏览器来访问服务。（该操作需要操作系统支持）
max_payload_size (int/str) – Tornado Server可以接受的最大websocket消息的大小。超过 max_payload_size (默认 200MB) 的消息会被拒绝接受。 max_payload_size 可以是整形表示的字节数或以 K / M / G 结尾的字符串，比如: 500, '40K', '3M'
tornado_app_settings – 传递给 tornado.web.Application 构造函数的额外的关键字参数可设置项参考: https://www.tornadoweb.org/en/stable/web.html#tornado.web.Application.settings

pywebio.platform.tornado.webio_handler(applications, cdn=True, reconnect_timeout=0, allowed_origins=None, check_origin=None)[源代码]¶

获取在Tornado中运行PyWebIO应用的RequestHandler类。RequestHandler类基于WebSocket协议与浏览器进行通讯。

关于各参数的详细说明见 pywebio.platform.tornado.start_server() 的同名参数。

HTTP¶

pywebio.platform.tornado_http.start_server(applications, port=8080, host='', debug=False, cdn=True, static_dir=None, allowed_origins=None, check_origin=None, auto_open_webbrowser=False, session_expire_seconds=None, session_cleanup_interval=None, max_payload_size='200M', **tornado_app_settings)[源代码]¶

启动一个 Tornado server 将PyWebIO应用作为Web服务提供。

服务端使用HTTP协议与浏览器进行通讯。

参数

session_expire_seconds (int) – 会话过期时间，单位为秒（默认60秒）。若 session_expire_seconds 秒内没有收到客户端的请求，则认为会话过期。
session_cleanup_interval (int) – 会话清理间隔，单位为秒(默认12秒)。服务端会周期性清理过期的会话，释放会话占用的资源。
max_payload_size (int/str) – Tornado Server可以接受的最大单个HTTP请求的大小

剩余参数的详细说明见 pywebio.platform.tornado.start_server() 的同名参数。

1.2 新版功能.

pywebio.platform.tornado_http.webio_handler(applications, cdn=True, session_expire_seconds=None, session_cleanup_interval=None, allowed_origins=None, check_origin=None)[源代码]¶

获取在Tornado中运行PyWebIO应用的RequestHandler类。RequestHandler类基于HTTP协议与浏览器进行通讯。

关于各参数的详细说明见 pywebio.platform.tornado_http.start_server() 的同名参数。

1.2 新版功能.

Flask support¶

使用Flask后端作为PyWebIO应用Server时，需要您自行安装Flask，并确保版本大于等于 0.10 。可通过以下命令安装:

pip3 install -U flask>=0.10

pywebio.platform.flask.webio_view(applications, cdn=True, session_expire_seconds=None, session_cleanup_interval=None, allowed_origins=None, check_origin=None)[源代码]¶

获取在Flask中运行PyWebIO任务的视图函数。基于http请求与前端页面进行通讯

关于各参数的详细说明见 pywebio.platform.flask.start_server() 的同名参数。

pywebio.platform.flask.wsgi_app(applications, cdn=True, static_dir=None, allowed_origins=None, check_origin=None, session_expire_seconds=None, session_cleanup_interval=None, max_payload_size='200M')[源代码]¶

将PyWebIO应用转换为Flask WSGI 应用

关于各参数的详细说明见 pywebio.platform.flask.start_server() 的同名参数。

pywebio.platform.flask.start_server(applications, port=8080, host='', cdn=True, static_dir=None, remote_access=False, allowed_origins=None, check_origin=None, session_expire_seconds=None, session_cleanup_interval=None, debug=False, max_payload_size='200M', **flask_options)[源代码]¶

启动一个 Flask server 将PyWebIO应用作为Web服务提供。

参数

session_expire_seconds (int) – 会话过期时间，单位为秒（默认600秒）。若 session_expire_seconds 秒内没有收到客户端的请求，则认为会话过期。
session_cleanup_interval (int) – 会话清理间隔，单位为秒(默认300秒)。服务端会周期性清理过期的会话，释放会话占用的资源。
debug (bool) – 是否开启Flask Server的debug模式，开启后，代码发生修改后服务器会自动重启。
max_payload_size (int/str) – Flask Server可以接受的最大单个HTTP请求的大小
flask_options – 传递给 flask.Flask.run 函数的额外的关键字参数可设置项参考: https://flask.palletsprojects.com/en/1.1.x/api/#flask.Flask.run

关于各参数的详细说明见 pywebio.platform.tornado.start_server() 的同名参数

Django support¶

使用Django后端作为PyWebIO应用Server时，需要您自行安装Django，并确保版本大于等于 2.2 。可通过以下命令安装:

pip3 install -U django>=2.2

pywebio.platform.django.webio_view(applications, cdn=True, session_expire_seconds=None, session_cleanup_interval=None, allowed_origins=None, check_origin=None)[源代码]¶

获取在django中运行PyWebIO任务的视图函数。基于http请求与前端进行通讯

关于各参数的详细说明见 pywebio.platform.flask.webio_view() 的同名参数。

pywebio.platform.django.wsgi_app(applications, cdn=True, static_dir=None, allowed_origins=None, check_origin=None, session_expire_seconds=None, session_cleanup_interval=None, debug=False, max_payload_size='200M', **django_options)[源代码]¶

将PyWebIO应用转换为Django WSGI 应用

关于各参数的详细说明见 pywebio.platform.django.start_server() 的同名参数。

pywebio.platform.django.start_server(applications, port=8080, host='', cdn=True, static_dir=None, remote_access=False, allowed_origins=None, check_origin=None, session_expire_seconds=None, session_cleanup_interval=None, debug=False, max_payload_size='200M', **django_options)[源代码]¶

启动一个 Django server 将PyWebIO应用作为Web服务提供。

参数

debug (bool) – 开启 Django debug mode。参见 Django doc .
django_options – django应用的其他设置，见 https://docs.djangoproject.com/en/3.0/ref/settings/ . 其中 DEBUG 、 ALLOWED_HOSTS 、 ROOT_URLCONF 、 SECRET_KEY 被PyWebIO设置，无法在 django_options 中指定

剩余参数的详细说明见 pywebio.platform.flask.start_server() 的同名参数。

aiohttp support¶

使用aiohttp后端作为PyWebIO应用Server时，需要您自行安装aiohttp，并确保版本大于等于 3.1 。可通过以下命令安装:

pip3 install -U aiohttp>=3.1

pywebio.platform.aiohttp.webio_handler(applications, cdn=True, allowed_origins=None, check_origin=None, websocket_settings=None)[源代码]¶

获取在aiohttp中运行PyWebIO任务函数的 Request Handler 协程。Request Handler基于WebSocket协议与浏览器进行通讯。

关于 applications 、 allowed_origins 、 check_origin 参数的详细说明见 pywebio.platform.aiohttp.start_server() 的同名参数。

返回: aiohttp Request Handler

pywebio.platform.aiohttp.start_server(applications, port=0, host='', debug=False, cdn=True, static_dir=None, remote_access=False, allowed_origins=None, check_origin=None, auto_open_webbrowser=False, websocket_settings=None, **aiohttp_settings)[源代码]¶

启动一个 aiohttp server 将PyWebIO应用作为Web服务提供。

参数

websocket_settings (dict) – 创建 aiohttp WebSocketResponse 时使用的参数。见 https://docs.aiohttp.org/en/stable/web_reference.html#websocketresponse
aiohttp_settings – 需要传给 aiohttp Application 的参数。可用参数见 https://docs.aiohttp.org/en/stable/web_reference.html#application

剩余参数的详细说明见 pywebio.platform.tornado.start_server() 的同名参数。

FastAPI/Starlette support¶

当使用FastAPI/Starlette作为PyWebIO的后端server时，你需要手动安装 fastapi 或 starlette ，另外还需要安装一些其他的依赖库，可以使用以下命令安装:

pip3 install -U fastapi starlette uvicorn aiofiles websockets

pywebio.platform.fastapi.webio_routes(applications, cdn=True, allowed_origins=None, check_origin=None)[源代码]¶

获取在FastAPI/Starlette中运行PyWebIO的路由组件。

服务端使用WebSocket协议与浏览器进行通讯。

关于各参数的详细说明见 pywebio.platform.fastapi.start_server() 的同名参数。

1.3 新版功能.

返回: FastAPI/Starlette routes

pywebio.platform.fastapi.asgi_app(applications, cdn=True, static_dir=None, debug=False, allowed_origins=None, check_origin=None)[源代码]¶

将PyWebIO应用转换为starlette/Fastapi ASGI应用

如果你需要自己托管静态文件，请使用 pywebio.platform.fastapi.webio_routes()

关于各参数的详细说明见 pywebio.platform.fastapi.start_server() 的同名参数。

Example

To be used with FastAPI.mount() to include pywebio as a subapp into an existing Starlette/FastAPI application:

from fastapi import FastAPI
from pywebio.platform.fastapi import asgi_app
from pywebio.output import put_text
app = FastAPI()
subapp = asgi_app(lambda: put_text("hello from pywebio"))
app.mount("/pywebio", subapp)

Returns: Starlette/Fastapi ASGI app

1.3 新版功能.

pywebio.platform.fastapi.start_server(applications, port=0, host='', cdn=True, static_dir=None, remote_access=False, debug=False, allowed_origins=None, check_origin=None, auto_open_webbrowser=False, **uvicorn_settings)[源代码]¶

启动一个 FastAPI/Starlette server 将PyWebIO应用作为Web服务提供。

参数

debug (bool) – 发生异常时是否打印调用栈。
uvicorn_settings – 传递给 uvicorn.run() 的额外关键字参数可设置项参考: https://www.uvicorn.org/settings/

剩余参数的详细说明见 pywebio.platform.tornado.start_server() 的同名参数。

1.3 新版功能.

其他¶

pywebio.platform.seo(title, description=None, app=None)[源代码]¶

设置PyWebIO应用的SEO信息（在被搜索引擎索引时提供的网页信息）

参数

title (str) – 应用标题
description (str) – 应用简介
app (callable) – PyWebIO任务函数

除了使用 seo() 函数，PyWebIO默认会将任务函数的函数注释作为SEO信息:

可以通过装饰器或直接调用的方式使用 seo()

@seo("title", "description")
def foo():
    pass

def bar():
    pass

def hello():
    """应用标题

    应用简介…
    (应用简介和标题之间使用一个空行分隔)
    """

start_server([
    foo,
    hello,
    seo("title", "description", bar),
])

1.1 新版功能.

pywebio.platform.run_event_loop(debug=False)[源代码]¶

运行 asyncio 事件循环

参数: debug – Set the debug mode of the event loop. See also: https://docs.python.org/3/library/asyncio-dev.html#asyncio-debug-mode

pywebio.platform — 应用部署¶

Directory Deploy¶

Application Deploy¶

Tornado相关¶

WebSocket¶

HTTP¶

Flask support¶

Django support¶

aiohttp support¶

FastAPI/Starlette support¶

其他¶

`pywebio.platform` — 应用部署¶