Brython 浏览器对象存储指南:使用 ObjectStorage 在 local/session storage 中存取 Python 对象

  • 编程语言
  • 语言运行时
  • 编译器
  • 前端

【免费下载链接】brython

Brython (Browser Python) is an implementation of Python 3 running in the browser

项目地址: https://gitcode.com/gh_mirrors/br/brython
点击查看 免费下载

导读

本文围绕 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 的差异:

  1. keys() / values() / items() 返回的是列表副本而非视图(与 local_storage 的设计注释一致,Brython 出于性能和实现简洁考虑采用列表)。
  2. 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

项目地址: https://gitcode.com/gh_mirrors/br/brython
点击查看 免费下载

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值