pywebio.session
— 会话相关¶
-
pywebio.session.
run_async
(coro_obj)[源代码]¶ 异步运行协程对象。协程中依然可以调用 PyWebIO 交互函数。
run_async()
仅能在 基于协程 的会话上下文中调用- 参数
coro_obj – 协程对象
- 返回
TaskHandle
实例。 通过 TaskHandle 可以查询协程运行状态和关闭协程。
参见:协程会话的并发
-
pywebio.session.
run_asyncio_coroutine
(coro_obj)[源代码]¶ 若会话线程和运行asyncio事件循环的线程不是同一个线程,需要用
run_asyncio_coroutine()
来运行asyncio中的协程。仅能在 基于协程 的会话上下文中调用。
- 参数
coro_obj –
asyncio
库中的协程对象
Example:
async def app(): put_text('hello') await run_asyncio_coroutine(asyncio.sleep(1)) put_text('world') pywebio.platform.flask.start_server(app)
-
pywebio.session.
download
(name, content)[源代码]¶ 向用户推送文件,用户浏览器会将文件下载到本地
- 参数
name (str) – 下载保存为的文件名
content – 文件内容. 类型为 bytes-like object
Example:
put_buttons(['Click to download'], [lambda: download('hello-world.txt', b'hello world!')])
-
pywebio.session.
run_js
(code_, **args)[源代码]¶ 在用户浏览器中运行JavaScript代码.
代码运行在浏览器的JS全局作用域中
- 参数
code (str) – js代码
args – 传递给js代码的局部变量。变量值需要可以被json序列化
Example:
run_js('console.log(a + b)', a=1, b=2)
-
pywebio.session.
eval_js
(expression_, **args)[源代码]¶ 在用户浏览器中执行JavaScript表达式,并获取表达式的值
- 参数
expression (str) – JavaScript表达式。表达式的值需要可以被JSON序列化。如果表达式的值是一个`promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ ,
eval_js()
会一直等待promise被resolve,然后返回它的值,若promise被reject,则返回None
。args – 传递给js代码的局部变量。变量值需要可以被json序列化
- 返回
js表达式的值
注意⚠️:在 基于协程 的会话上下文中,需要使用
await eval_js(expression)
语法来进行调用。Example:
current_url = eval_js("window.location.href") function_res = eval_js('''(function(){ var a = 1; a += b; return a; })()''', b=100) promise_res = eval_js('''new Promise(resolve => { setTimeout(() => { resolve('Returned inside callback.'); }, 2000); });''')
在 1.3 版更改: The JS expression support return promise.
-
pywebio.session.
register_thread
(thread: threading.Thread)[源代码]¶ 注册线程,以便在线程内调用 PyWebIO 交互函数。
仅能在默认的基于线程的会话上下文中调用。
- 参数
thread (threading.Thread) – 线程对象
-
pywebio.session.
defer_call
(func)[源代码]¶ 设置会话结束时调用的函数。
无论是用户主动关闭会话还是任务结束会话关闭,设置的函数都会被运行。
在会话中可以多次调用
defer_call()
,会话结束后将会顺序执行设置的函数。defer_call
同样支持以装饰器的方式使用:@defer_call def cleanup(): pass
注意
通过
defer_call()
设置的函数被调用时会话已经关闭,所以在函数体内不可以调用 PyWebIO 的交互函数
-
pywebio.session.
hold
()[源代码]¶ 保持会话,直到用户关闭浏览器。
注解
在PyWebIO会话结束后,页面和服务端的连接便会断开, 页面上需要和服务端通信才可实现的功能(比如:下载通过
put_file()
输出的文件,put_buttons()
按钮回调)便无法使用。 可以在任务函数末尾处调用hold()
函数来将会话保持,这样在用户关闭浏览器页面前,会话将一直保持连接。注意⚠️:在 基于协程 的会话上下文中,需要使用
await hold()
语法来进行调用。
-
pywebio.session.
local
¶ 当前会话的数据对象(session-local object)。
local
是一个可以通过属性访问的字典,访问不存在的属性时会返回None
而不是抛出异常。local
不支持字典的方法,支持使用in
操作符来判断键是否存在,可以使用local._dict
获取底层的字典表示。- 使用场景
当需要在多个函数中保存一些会话独立的数据时,使用session-local对象保存状态会比通过函数参数传递更方便。
以下是一个会话独立的计数器的实现示例:
from pywebio.session import local def add(): local.cnt = (local.cnt or 0) + 1 def show(): put_text(local.cnt or 0) def main(): put_buttons(['Add counter', 'Show counter'], [add, show]) hold()
而通过函数参数传递状态的实现方式为:
from functools import partial def add(cnt): cnt[0] += 1 def show(cnt): put_text(cnt[0]) def main(): cnt = [0] # Trick: to pass by reference put_buttons(['Add counter', 'Show counter'], [partial(add, cnt), partial(show, cnt)]) hold()
当然,还可以通过函数闭包来实现相同的功能:
def main(): cnt = 0 def add(): nonlocal cnt cnt += 1 def show(): put_text(cnt) put_buttons(['Add counter', 'Show counter'], [add, show]) hold()
- local 支持的操作
local.name = "Wang" local.age = 22 assert local.foo is None local[10] = "10" for key in local: print(key) assert 'bar' not in local assert 'name' in local print(local._dict)
1.1 新版功能.
-
pywebio.session.
set_env
(**env_info)[源代码]¶ 当前会话的环境设置
可配置项有:
title
(str): 当前页面的标题output_animation
(bool): 是否启用输出动画(在输出内容时,使用过渡动画),默认启用auto_scroll_bottom
(bool): 是否在内容输出时将页面自动滚动到底部,默认关闭。注意,开启后,只有输出到ROOT Scope才可以触发自动滚动。http_pull_interval
(int): HTTP轮询后端消息的周期(单位为毫秒,默认1000ms),仅在基于HTTP连接的会话(使用Flask或Django后端)中可用input_panel_fixed
(bool): 是否将输入栏固定在页面底部, 默认启用。input_panel_min_height
(int): 输入栏的最小高度(像素, 默认为300px,最小允许 75px)。仅当input_panel_fixed=True
时可用。input_panel_init_height
(int): 输入栏的初始高度(像素, 默认为300px,最小允许 175px)。仅当input_panel_fixed=True
时可用。input_auto_focus
(bool): 输入栏是否自动获取输入焦点,默认为True
。
Example:
set_env(title='Awesome PyWebIO!!', output_animation=False)
-
pywebio.session.
go_app
(name, new_window=True)[源代码]¶ 在同一PyWebIO应用的不同服务之间跳转。仅在PyWebIO Server模式下可用
- 参数
name (str) – 目标 PyWebIO 任务名
new_window (bool) – 是否在新窗口打开,默认为
True
参见: Server 模式
-
pywebio.session.
info
¶ 表示会话信息的对象,属性有:
user_agent
: 表示用户浏览器信息的对象,属性有is_mobile
(bool): 用户使用的设备是否为手机 (比如 iPhone, Android phones, Blackberry, Windows Phone 等设备)is_tablet
(bool): 用户使用的设备是否为平板 (比如 iPad, Kindle Fire, Nexus 7 等设备)is_pc
(bool): 用户使用的设备是否为桌面电脑 (比如运行 Windows, OS X, Linux 的设备)is_touch_capable
(bool): 用户使用的设备是否支持触控browser.family
(str): 浏览器家族. 比如 ‘Mobile Safari’browser.version
(tuple): 浏览器版本元组. 比如 (5, 1)browser.version_string
(str): 浏览器版本字符串. 比如 ‘5.1’os.family
(str): 操作系统家族. 比如 ‘iOS’os.version
(tuple): 操作系统版本元组. 比如 (5, 1)os.version_string
(str): 操作系统版本字符串. 比如 ‘5.1’device.family
(str): 设备家族. 比如 ‘iPhone’device.brand
(str): 设备品牌. 比如 ‘Apple’device.model
(str): 设备型号. 比如 ‘iPhone’
user_language
(str): 用户操作系统使用的语言. 比如'zh-CN'
server_host
(str): 当前会话的服务器host,包含域名和端口,端口为80时可以被省略origin
(str): 当前用户的页面地址. 包含 协议、主机、端口 部分. 比如'http://localhost:8080'
. 可能为空,但保证当用户的页面地址不在当前服务器下(即 主机、端口部分和server_host
不一致)时有值.user_ip
(str): 用户的ip地址.backend
(str): 当前PyWebIO使用的后端Server实现. 可能出现的值有'tornado'
,'flask'
,'django'
,'aiohttp'
,'starlette'
.protocol
(str): PyWebIO服务器与浏览器之间的通信协议。可能的值为'websocket'
或'http'
request
(object): 创建当前会话时的Web请求对象. 根据PyWebIO使用的后端Server不同,request
的类型也不同:使用Tornado后端时,
request
为 tornado.httputil.HTTPServerRequest 实例使用Flask后端时,
request
为 flask.Request 实例使用Django后端时,
request
为 django.http.HttpRequest 实例使用aiohttp后端时,
request
为 aiohttp.web.BaseRequest 实例当使用FastAPI或Starlette时,
request
属性为 starlette.websockets.WebSocket 实例
会话信息对象的
user_agent
属性是通过 user-agents 库进行解析生成的。参见 https://github.com/selwin/python-user-agents#usage在 1.2 版更改: Added the
protocol
attribute.Example:
import json from pywebio.session import info as session_info put_code(json.dumps({ k: str(getattr(session_info, k)) for k in ['user_agent', 'user_language', 'server_host', 'origin', 'user_ip', 'backend', 'protocol', 'request'] }, indent=4), 'json')