pywebio.platform — Web框架支持

platform 模块为PyWebIO提供了对不同Web框架的支持。

具体用法参见用户手册 与Web框架集成 小节

Tornado相关

pywebio.platform.tornado.start_server(applications, port=0, host='', debug=False, allowed_origins=None, check_origin=None, auto_open_webbrowser=False, websocket_max_message_size=None, websocket_ping_interval=None, websocket_ping_timeout=None, **tornado_app_settings)

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

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

参数

• applications (list/dict/callable) –

  PyWebIO应用. 可以是任务函数或者任务函数的字典或列表。

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

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

  任务函数为协程函数时，使用 基于协程的会话实现 ；任务函数为普通函数时，使用基于线程的会话实现。

• port (int) – 服务监听的端口。设置为 0 时，表示自动选择可用端口。

• host (str) – 服务绑定的地址。 host 可以是IP地址或者为hostname。如果为hostname，服务会监听所有与该hostname关联的IP地址。 通过设置 host 为空字符串或 None 来将服务绑定到所有可用的地址上。

• debug (bool) – Tornado Server是否开启debug模式

• allowed_origins (list) –

  除当前域名外，服务器还允许的请求的来源列表。 来源包含协议、域名和端口部分，允许使用 Unix shell 风格的匹配模式(全部规则参见 Python文档 ):

  • * 为通配符

  • ? 匹配单个字符

  • [seq] 匹配seq中的任何字符

  • [!seq] 匹配任何不在seq中的字符

  比如 https://*.example.com 、 *://*.example.com

• check_origin (callable) – 请求来源检查函数。接收请求来源(包含协议、域名和端口部分)字符串， 返回 True/False 。若设置了 check_origin ， allowed_origins 参数将被忽略

• auto_open_webbrowser (bool) – 当服务启动后，是否自动打开浏览器来访问服务。（该操作需要操作系统支持）

• websocket_max_message_size (int) – Tornado Server最大可接受的WebSockets消息大小。单位为字节，默认为10MiB。

• websocket_ping_interval (int) – 当被设置后，服务器会以 websocket_ping_interval 秒周期性地向每个WebSockets连接发送‘ping‘消息。 如果应用处在某些反向代理服务器之后，设置 websocket_ping_interval 可以避免WebSockets连接被代理服务器当作空闲连接而关闭。 同时，若WebSockets连接在某些情况下被异常关闭，应用也可以及时感知。

• websocket_ping_timeout (int) – 如果设置了 websocket_ping_interval ，而服务没有在发送‘ping‘消息后的 websocket_ping_timeout 秒 内收到‘pong’消息，应用会将连接关闭。默认的超时时间为 websocket_ping_interval 的三倍。

• tornado_app_settings – 传递给 tornado.web.Application 构造函数的额外的关键字参数 可设置项参考: https://www.tornadoweb.org/en/stable/web.html#tornado.web.Application.settings

pywebio.platform.tornado.webio_handler(applications, allowed_origins=None, check_origin=None)

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

参数

• applications (callable/list/dict) – PyWebIO应用。

• allowed_origins (list) – 除当前域名外，服务器还允许的请求的来源列表。

• check_origin (callable) – 请求来源检查函数。

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

返回

Tornado RequestHandle类

Flask相关

pywebio.platform.flask.webio_view(applications, session_expire_seconds=None, session_cleanup_interval=None, allowed_origins=None, check_origin=None)

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

参数

• applications (list/dict/callable) – PyWebIO应用。

• session_expire_seconds (int) – 会话不活跃过期时间。

• session_cleanup_interval (int) – 会话清理间隔。

• allowed_origins (list) – 除当前域名外，服务器还允许的请求的来源列表。

• check_origin (callable) – 请求来源检查函数。

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

返回

Flask视图函数

pywebio.platform.flask.start_server(applications, port=8080, host='localhost', allowed_origins=None, check_origin=None, disable_asyncio=False, session_cleanup_interval=None, session_expire_seconds=None, debug=False, **flask_options)

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

参数

• applications (list/dict/callable) – PyWebIO应用. 格式同 pywebio.platform.tornado.start_server() 的 applications 参数

• port (int) – 服务监听的端口。设置为 0 时，表示自动选择可用端口。

• host (str) – 服务绑定的地址。 host 可以是IP地址或者为hostname。如果为hostname，服务会监听所有与该hostname关联的IP地址。 通过设置 host 为空字符串或 None 来将服务绑定到所有可用的地址上。

• allowed_origins (list) –

  除当前域名外，服务器还允许的请求的来源列表。 来源包含协议、域名和端口部分，允许使用 Unix shell 风格的匹配模式(全部规则参见 Python文档 ):

  • * 为通配符

  • ? 匹配单个字符

  • [seq] 匹配seq中的字符

  • [!seq] 匹配不在seq中的字符

  比如 https://*.example.com 、 *://*.example.com

• check_origin (callable) – 请求来源检查函数。接收请求来源(包含协议、域名和端口部分)字符串， 返回 True/False 。若设置了 check_origin ， allowed_origins 参数将被忽略

• disable_asyncio (bool) –

  禁用 asyncio 函数。仅在任务函数为协程函数时有效。

  注解

  实现说明： 当使用Flask backend时，若要在PyWebIO的会话中使用 asyncio 标准库里的协程函数，PyWebIO需要单独开启一个线程来运行 asyncio 事件循环， 若程序中没有使用到 asyncio 中的异步函数，可以开启此选项来避免不必要的资源浪费

• session_expire_seconds (int) – 会话过期时间。若 session_expire_seconds 秒内没有收到客户端的请求，则认为会话过期。

• session_cleanup_interval (int) – 会话清理间隔。

• debug (bool) – Flask debug mode

• flask_options – 传递给 flask.Flask.run 函数的额外的关键字参数 可设置项参考: https://flask.palletsprojects.com/en/1.1.x/api/#flask.Flask.run

Django相关

pywebio.platform.django.webio_view(applications, session_expire_seconds=None, session_cleanup_interval=None, allowed_origins=None, check_origin=None)

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

参数

• applications (list/dict/callable) – PyWebIO应用。

• session_expire_seconds (int) – 会话不活跃过期时间。

• session_cleanup_interval (int) – 会话清理间隔。

• allowed_origins (list) – 除当前域名外，服务器还允许的请求的来源列表。

• check_origin (callable) – 请求来源检查函数。

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

返回

Django视图函数

pywebio.platform.django.start_server(applications, port=8080, host='localhost', allowed_origins=None, check_origin=None, disable_asyncio=False, session_cleanup_interval=None, session_expire_seconds=None, debug=False, **django_options)

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

参数

• applications (list/dict/callable) – PyWebIO应用. 格式同 pywebio.platform.tornado.start_server() 的 applications 参数

• port (int) – 服务监听的端口。设置为 0 时，表示自动选择可用端口。

• host (str) – 服务绑定的地址。 host 可以是IP地址或者为hostname。如果为hostname，服务会监听所有与该hostname关联的IP地址。 通过设置 host 为空字符串或 None 来将服务绑定到所有可用的地址上。

• allowed_origins (list) –

  除当前域名外，服务器还允许的请求的来源列表。 来源包含协议、域名和端口部分，允许使用 Unix shell 风格的匹配模式(全部规则参见 Python文档 ):

  • * 为通配符

  • ? 匹配单个字符

  • [seq] 匹配seq中的字符

  • [!seq] 匹配不在seq中的字符

  比如 https://*.example.com 、 *://*.example.com

• check_origin (callable) – 请求来源检查函数。接收请求来源(包含协议、域名和端口部分)字符串， 返回 True/False 。若设置了 check_origin ， allowed_origins 参数将被忽略

• disable_asyncio (bool) –

  禁用 asyncio 函数。仅在任务函数为协程函数时有效。

  注解

  实现说明： 当使用Django backend时，若要在PyWebIO的会话中使用 asyncio 标准库里的协程函数，PyWebIO需要单独开启一个线程来运行 asyncio 事件循环， 若程序中没有使用到 asyncio 中的异步函数，可以开启此选项来避免不必要的资源浪费

• session_expire_seconds (int) – 会话过期时间。若 session_expire_seconds 秒内没有收到客户端的请求，则认为会话过期。

• session_cleanup_interval (int) – 会话清理间隔。

• debug (bool) – 开启 Django debug mode 和一般访问日志的记录

• django_options – django应用的其他设置，见 https://docs.djangoproject.com/en/3.0/ref/settings/ . 其中 DEBUG 、 ALLOWED_HOSTS 、 ROOT_URLCONF 、 SECRET_KEY 被PyWebIO设置，无法在 django_options 中指定

aiohttp相关

pywebio.platform.aiohttp.webio_handler(applications, allowed_origins=None, check_origin=None, websocket_settings=None)

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

参数

• applications (list/dict/callable) – PyWebIO应用。

• allowed_origins (list) – 除当前域名外，服务器还允许的请求的来源列表。

• check_origin (callable) – 请求来源检查函数。

• websocket_settings (dict) – 创建 aiohttp WebSocketResponse 时使用的参数。见 https://docs.aiohttp.org/en/stable/web_reference.html#websocketresponse

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

返回

aiohttp Request Handler

pywebio.platform.aiohttp.static_routes(prefix='/')

获取用于提供PyWebIO静态文件的aiohttp路由列表

参数

prefix (str) – 静态文件托管的URL路径，默认为根路径 /

返回

aiohttp路由列表

pywebio.platform.aiohttp.start_server(applications, port=0, host='', debug=False, allowed_origins=None, check_origin=None, auto_open_webbrowser=False, websocket_settings=None, **aiohttp_settings)

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

参数

• applications (list/dict/callable) – PyWebIO应用. 格式同 pywebio.platform.tornado.start_server() 的 applications 参数

• port (int) – 服务监听的端口。设置为 0 时，表示自动选择可用端口。

• host (str) – 服务绑定的地址。 host 可以是IP地址或者为hostname。如果为hostname，服务会监听所有与该hostname关联的IP地址。 通过设置 host 为空字符串或 None 来将服务绑定到所有可用的地址上。

• debug (bool) – 是否开启asyncio的Debug模式

• allowed_origins (list) –

  除当前域名外，服务器还允许的请求的来源列表。 来源包含协议、域名和端口部分，允许使用 Unix shell 风格的匹配模式(全部规则参见 Python文档 ):

  • * 为通配符

  • ? 匹配单个字符

  • [seq] 匹配seq中的字符

  • [!seq] 匹配不在seq中的字符

  比如 https://*.example.com 、 *://*.example.com

• check_origin (callable) – 请求来源检查函数。接收请求来源(包含协议、域名和端口部分)字符串， 返回 True/False 。若设置了 check_origin ， allowed_origins 参数将被忽略

• auto_open_webbrowser (bool) – 当服务启动后，是否自动打开浏览器来访问服务。（该操作需要操作系统支持）

• 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.httpbased.run_event_loop(debug=False)

运行事件循环

基于协程的会话在启动基于线程的http服务器之前需要启动一个单独的线程来运行事件循环。

参数

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