【免费下载链接】brython
Brython (Browser Python) is an implementation of Python 3 running in the browser
导读
本文围绕 Brython(Browser Python,在浏览器中运行的 Python 3 实现)的标准库模块 browser.object_storage 展开,讲解如何在 HTML5 的 local storage / session storage 之上,以 Python 字典风格存取非字符串的 Python 对象(如 list、dict)。读完本文,你将掌握 ObjectStorage 类的完整 API、JSON 序列化背后的实现原理、对象不可变性的来源与正确更新策略,并能结合 browser.local_storage 与 browser.session_storage 的底层机制,在真实 Brython 页面中写出可运行、可验证的持久化代码。
背景:为什么需要 ObjectStorage
在 HTML5 规范中,local storage 与 session storage 本质上是浏览器端的键值数据库,但键与值都只能是字符串。Brython 通过 browser 包下的两个模块向 Python 代码暴露了与之对应的存储对象:
- browser.local_storage:持久化存储,关闭浏览器窗口后数据仍然保留,作用域限定在
scheme://host:port这一 HTML5 origin 内(即同协议、同域名、同端口的所有页面共享); - browser.session_storage:会话级存储,浏览器窗口关闭后数据即丢失,适合存放登录令牌等不希望跨会话共享的数据。
上述两个模块均通过 from browser.xxx_storage import storage 暴露一个字典风格的 storage 对象。但正如 local_storage 的实现所示,其 __setitem__ 强制要求 key 和 value 都必须是字符串(否则抛出 TypeError)。这意味着一行 storage['count'] = 42 或 storage['config'] = {"theme": "dark"} 在底层会直接失败。
browser.object_storage 模块正是为解决这一限制而生:它包装底层的 storage 对象,在读写两侧自动完成 JSON 序列化与反序列化,让 Python 开发者可以用近乎原生 dict 的方式,把 list、dict、数字、布尔值等 JSON 可序列化对象持久化到浏览器存储中。
ObjectStorage 类与构造方式
模块导出一个类:
ObjectStorage(_storage_)
参数 _storage_ 必须是 browser.session_storage 或 browser.local_storage 暴露出的 storage 对象。也就是说,ObjectStorage 是一个薄包装层,它并不自己管理存储,而是把序列化后的字符串转交给底层 storage 完成落盘。
from browser.session_storage import storage
from browser.object_storage import ObjectStorage
object_storage = ObjectStorage(storage)
选择哪个底层 storage,决定了数据的生命周期:
- 传入
local_storage的storage,数据在浏览器关闭后依然保留; - 传入
session_storage的storage,数据随浏览器窗口关闭而消失。
序列化原理:JSON 是唯一的通道
从 object_storage 源码 可以看到,整个模块的核心逻辑只有几行:所有读写都经由 json.dumps 与 json.loads 完成。
import json
class ObjectStorage():
def __init__(self, storage):
self.storage = storage
def __setitem__(self, key, value):
self.storage[json.dumps(key)] = json.dumps(value)
def __getitem__(self, key):
return json.loads(self.storage[json.dumps(key)])
这意味着:
- 存入时,key 与 value 先经
json.dumps转换为 JSON 字符串,再写入底层 storage; - 读取时,先从底层 storage 取出 JSON 字符串,再经
json.loads还原为 Python 对象; - 因此只支持 JSON 可序列化的对象,典型如
list、dict、str、int、float、bool、None; - 自定义类实例、
set、bytes等无法被 JSON 编码的对象不能直接存储。
一个额外的收益是:因为 key 也被序列化,所以 key 同样可以是非字符串对象。例如 object_storage[['do', 're', 'me']] 中的列表 ['do', 're', 'me'] 会被 json.dumps 编码为 ["do", "re", "me"] 作为底层键,从而与底层的纯字符串存储完全兼容。
存储对象的不可变性与更新策略
文档特别强调了一个容易被忽略的行为:对象一旦存入就变成“不可变”的。
object_storage[['do', 're', 'me']] = {"tune": "in tune"}
object_storage[['do', 're', 'me']].update({"duration": "one hour"}) # 不会生效!
为什么 .update(...) 无效?因为 __getitem__ 的实现是 json.loads(self.storage[json.dumps(key)])——它每次读取时都新构造一个 Python 对象。你对这个新对象做 update 修改的只是临时副本,底层 storage 里保存的仍是当初序列化的那串 JSON。修改结果从未被写回,自然“什么都不发生”。
正确做法是先取出、再修改、最后整体写回,这正是文档给出的模式:
# 先复制出来
tmp = object_storage[['do', 're', 'me']]
tmp.update({"duration": "one hour"})
# 修改完成后整体写回
object_storage[['do', 're', 'me']] = tmp
结合 test_storage.py 测试用例 可以验证这一写读往返是正确的:测试中先写入 object_storage['mah'] = {"hi": 5},再读取并断言 object_storage['mah'] == {'hi': 5},证实 JSON 编码/解码往返能完好还原嵌套 dict 与嵌套 list。
完整 API 一览
ObjectStorage 实现了与底层 storage(以及 Python dict)风格一致的接口。以下 API 均可在 object_storage.py 中查证:
| 方法/语法 | 作用 | 底层实现要点 |
|---|---|---|
store[key] = value | 存入对象(key/value 均 JSON 序列化) | self.storage[json.dumps(key)] = json.dumps(value) |
store[key] | 读取并反序列化对象 | json.loads(self.storage[json.dumps(key)]) |
del store[key] | 删除键 | del self.storage[json.dumps(key)] |
key in store | 判断键是否存在 | json.dumps(key) in self.storage |
store.get(key, default=None) | 安全读取,缺失时返回默认值 | 键存在时返回原始 JSON 字符串(注意:此处返回的是 JSON 字符串而非反序列化对象) |
store.pop(key, default=...) | 弹出并返回反序列化后的对象 | 缺失且未给默认值时同样返回 None(实现上未抛 KeyError) |
store.keys() | 返回所有键(已反序列化)的列表 | [json.loads(key) for key in self.storage.keys()] |
store.values() | 返回所有值(已反序列化)的列表 | [json.loads(val) for val in self.storage.values()] |
store.items() | 返回 (键, 值) 列表 | list(zip(self.keys(), self.values())) |
store.clear() | 清空全部数据 | self.storage.clear() |
len(store) | 键值对数量 | len(self.storage) |
for item in store | 迭代所有键 | 基于 self.keys() 的迭代器 |
需要留意两点与 Python 原生 dict 的差异:
keys()/values()/items()返回的是列表副本而非视图(与 local_storage 的设计注释一致,Brython 出于性能和实现简洁考虑采用列表)。pop的缺省行为:源码中pop(key, default=_UnProvided())在键缺失且未提供默认值时,json.loads(self.storage.pop(...))会对不存在的键执行pop得到None,因此返回None而不是抛出KeyError。这与底层 LocalStorage.pop 的行为(缺失且无默认值时抛KeyError)不同,使用时需按实际需求判断。
类型限制与注意事项
- 只支持 JSON 可序列化对象:
list、dict、str、数值、bool、None均可用;自定义对象、set、bytes、tuple等无法直接存储。若确需保存复杂结构,可先手动转换为 JSON 兼容形式(如把set转成list、tuple转成list)再存入。 - 键值皆序列化:因为底层始终是字符串键,所以读取时拿到的 key/value 都是反序列化后的全新对象,切勿假设它们与写入时是同一对象引用。
- 存储上限与作用域:
ObjectStorage不改变底层 storage 的容量与作用域约束——数据量受浏览器对 localStorage 的配额限制,且数据仅在同scheme://host:port下可见、按浏览器实例隔离(local storage 是 per-browser 而非 per-computer)。 - 存储类型选择:会话级临时数据用
session_storage的 storage,需要跨会话保留的数据用local_storage的 storage。
完整可运行示例
将以下代码放入 Brython 页面(页面需引入 brython.js 并在 onload 中调用 brython()):
from browser.local_storage import storage
from browser.object_storage import ObjectStorage
from browser import document
# 包装本地持久化存储
object_storage = ObjectStorage(storage)
# 写入:key 与 value 都可以是非字符串对象
object_storage[['do', 're', 'me']] = {"tune": "in tune"}
object_storage['counter'] = 42
# 读取:自动反序列化
tune = object_storage[['do', 're', 'me']]
document <= f"读取到的对象:{tune}"
# 更新:必须先取出、修改、再写回
tmp = object_storage[['do', 're', 'me']]
tmp.update({"duration": "one hour"})
object_storage[['do', 're', 'me']] = tmp
# 遍历、删除与清空
for key in object_storage:
print(key)
del object_storage[['do', 're', 'me']]
object_storage.clear()
该示例中的序列化往返、列表键、字典键、items() 迭代、del 删除等行为,均与仓库内的自动化测试 test_storage.py 覆盖的场景一致,可作为行为契约的参照。
小结
browser.object_storage 是 Brython 标准库中对 HTML5 Web Storage 的一次轻量而关键的增强:它用两个 JSON 调用(json.dumps / json.loads)把“仅字符串”的浏览器存储升级为“任意 JSON 对象”的 Python 字典风格存储。理解其每次读取都返回新对象的实现细节,就能解释为何存储后的对象“不可变”,并掌握“取出—修改—写回”这一唯一正确的更新姿势。结合 local_storage 源码 与 session_storage 源码 可以进一步看到,ObjectStorage 的所有持久化能力最终都委托给底层 storage,因此作用域、生命周期与容量限制完全继承自 HTML5 Web Storage 本身——选择正确的底层 storage,就是选择正确的数据生命周期。
【免费下载链接】brython
Brython (Browser Python) is an implementation of Python 3 running in the browser
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考



