y_py¶

Attributes¶

`Event`
`EncodedStateVector`
`EncodedDeleteSet`
`YDocUpdate`
`YTextDelta`
`YArrayObserver`
`ArrayDelta`	在事务期间对 `YArray` 的修改。
`YXmlAttributes`	生成 XML 元素的键/值属性序列。
`Xml`
`YXmlTreeWalker`	访问 XML 树中的元素。
`EntryChange`

Classes¶

`SubscriptionId`	跟踪观察者回调。将其传递给 unobserve 方法以取消其相关的回调。
`YDoc`	Ypy 文档类型。文档是协作资源管理中最重要的单位。
`AfterTransactionEvent`	保存事务更新信息，来自状态向量压缩后的提交。
`YTransaction`	作为文档块存储的代理的事务。Ypy 共享数据类型在给定事务的上下文中执行其操作。
`YText`	用于协作文本编辑的共享数据类型。它使多个用户能够高效地添加和删除文本块。
`YTextEvent`	传达在 `YText` 实例的事务期间发生的更新。
`YTextChangeInsert`	dict() -> new empty dictionary
`YTextChangeDelete`	dict() -> new empty dictionary
`YTextChangeRetain`	dict() -> new empty dictionary
`YArray`	创建一个新的 `YArray` 共享数据类型的初步实例，其状态初始化为提供的参数。
`YArrayEvent`	传达在 `YArray` 实例的事务期间发生的更新。
`ArrayChangeInsert`	更新消息，表示元素已插入到 `YArray` 中。
`ArrayChangeDelete`	更新消息，表示元素已从 `YArray` 中删除。
`ArrayChangeRetain`	更新消息，表示元素在 `YArray` 中未修改。
`YMap`	创建一个新的 YMap 共享数据类型的初步实例，其状态初始化为提供的参数。
`YMapItemsView`	跟踪 `YMap` 内的键/值。类似于 Python 字典的 dict_items 功能。
`YMapKeysView`	跟踪 `YMap` 内的键标识符。
`YMapValuesView`	跟踪 `YMap` 内的值。
`YMapEvent`	通信在 `YMap` 实例的事务期间发生的更新。
`YMapEventKeyChange`	dict() -> new empty dictionary
`YXmlElementEvent`
`YXmlElement`	XML 元素数据类型。它表示一个 XML 节点，可以包含键值属性（解释为字符串），
`YXmlFragment`	XML 片段数据类型。它表示一组 XML 节点。
`YXmlText`
`YXmlTextEvent`

Functions¶

`encode_state_vector`(→ EncodedStateVector)	将给定 Ypy 文档的状态向量编码为其二进制表示，使用 lib0 v1 编码。状态向量是对在给定文档上执行的更新的紧凑表示，可以在远程对等体上使用 `encode_state_as_update()` 生成增量更新有效负载，以同步对等体之间的更改。
`encode_state_as_update`(→ YDocUpdate)	将自给定版本 vector 以来发生的所有更新编码为紧凑的增量表示，使用 lib0 v1 编码。
`apply_update`(doc, diff)	将由远程文档副本生成的增量更新应用于当前文档。此方法假定有效负载保持 lib0 v1 编码格式。

Module Contents¶

class y_py.SubscriptionId¶: 跟踪观察者回调。将其传递给 unobserve 方法以取消其相关的回调。

y_py.Event¶

class y_py.YDoc(client_id: int | None = None, offset_kind: str = 'utf8', skip_gc: bool = False)¶

Ypy 文档类型。文档是协作资源管理中最重要的单位。所有共享集合都位于其对应文档的范围内。所有更新都是基于每个文档生成的（而不是单个共享类型）。所有对共享集合的操作都通过 YTransaction 进行，其生命周期也与文档相关。

文档管理所谓的根类型(root types)，这些是顶层共享类型定义(top-level shared types definitions)（与递归嵌套类型相对）。

Example:

from y_py import YDoc

doc = YDoc()
with doc.begin_transaction() as txn:
    text = txn.get_text('name')
    text.extend(txn, 'hello world')

print(str(text))

创建一个新的 Ypy 文档。如果传递了 client_id 参数，则将其用作该文档的全局唯一标识符（由调用者确保该要求）。否则，将分配一个随机生成的数字。

client_id: int¶

begin_transaction() → YTransaction¶

返回:: 此文档的新事务。Ypy 共享数据类型在给定事务的上下文中执行其操作。每个文档一次只能有一个活动事务 - 后续尝试将导致异常被抛出。

使用 begin_transaction() 开始的事务可以通过删除事务对象来释放。

Example:

from y_py import YDoc
doc = YDoc()
text = doc.get_text('name')
with doc.begin_transaction() as txn:
    text.insert(txn, 0, 'hello world')

transact(callback: Callable[[YTransaction]])¶

get_map(name: str) → YMap¶

返回:: 一个 YMap 共享数据类型，可以使用给定的 :arg:`name` 进行后续访问。

如果之前没有该名称的实例，将创建并返回它。

如果之前存在该名称的实例，但它是不同的类型，将投影到 YMap 实例上。

get_xml_element(name: str) → YXmlElement¶

返回:: 一个 YXmlElement 共享数据类型，可以使用给定的 name 进行后续访问。

如果之前没有该名称的实例，将创建并返回它。

如果之前存在该名称的实例，但它是不同的类型，将投影到 YXmlElement 实例上。

get_xml_text(name: str) → YXmlText¶

返回:: 一个 YXmlText 共享数据类型，可以使用给定的 name 进行后续访问。

如果之前没有该名称的实例，将创建并返回它。

如果之前存在该名称的实例，但它是不同的类型，将投影到 YXmlText 实例上。

get_xml_fragment(name: str) → YXmlFragment¶

返回:: 一个 YXmlFragment 共享数据类型，可以使用给定的 name 进行后续访问。

如果之前没有该名称的实例，将创建并返回它。

如果之前存在该名称的实例，但它是不同的类型，将投影到 YXmlFragment 实例上。

get_array(name: str) → YArray¶

:param 一个 YArray 共享数据类型，可以使用给定的 name 进行后续访问。:

如果之前没有该名称的实例，将创建并返回它。

如果之前存在该名称的实例，但它是不同的类型，将投影到 YArray 实例上。

get_text(name: str) → YText¶

参数:: name -- 用于检索文本的标识符
返回:: 一个 YText 共享数据类型，可以使用给定的 name 进行后续访问。

如果之前没有该名称的实例，将创建并返回它。如果之前存在该名称的实例，但它是不同的类型，将投影到 YText 实例上。

observe_after_transaction(callback: Callable[[AfterTransactionEvent]]) → SubscriptionId¶

订阅回调函数以接收 YDoc 的更新。当文档事务被提交时，回调将接收编码的状态更新和删除。

参数:: callback: 接收事务影响的 YDoc 状态信息的函数。

返回:: 一个可以用于取消回调的订阅标识符。

y_py.EncodedStateVector¶

y_py.EncodedDeleteSet¶

y_py.YDocUpdate¶

class y_py.AfterTransactionEvent¶

保存事务更新信息，来自状态向量压缩后的提交。

before_state: EncodedStateVector¶: 事务之前的 YDoc 编码状态。

after_state: EncodedStateVector¶: 事务之后的 YDoc 编码状态。

delete_set: EncodedDeleteSet¶: 由相关事务删除的元素。

get_update() → YDocUpdate¶

返回:: 由事务产生的所有更新的编码有效负载。

y_py.encode_state_vector(doc: YDoc) → EncodedStateVector¶

将给定 Ypy 文档的状态向量编码为其二进制表示，使用 lib0 v1 编码。状态向量是对在给定文档上执行的更新的紧凑表示，可以在远程对等体上使用 encode_state_as_update() 生成增量更新有效负载，以同步对等体之间的更改。

示例:

from y_py import YDoc, encode_state_vector, encode_state_as_update, apply_update from y_py

# 机器 A 上的文档
local_doc = YDoc()
local_sv = encode_state_vector(local_doc)

# 机器 B 上的文档
remote_doc = YDoc()
remote_delta = encode_state_as_update(remote_doc, local_sv)

apply_update(local_doc, remote_delta)

y_py.encode_state_as_update(doc: YDoc, vector: EncodedStateVector | List[int] | None = None) → YDocUpdate¶

将自给定版本 vector 以来发生的所有更新编码为紧凑的增量表示，使用 lib0 v1 编码。如果未提供 vector 参数，则生成的增量有效负载将包含当前 Ypy 文档的所有更改，有效地作为其状态快照。

示例:

from y_py import YDoc, encode_state_vector, encode_state_as_update, apply_update

# 机器 A 上的文档
local_doc = YDoc()
local_sv = encode_state_vector(local_doc)

# 机器 B 上的文档
remote_doc = YDoc()
remote_delta = encode_state_as_update(remote_doc, local_sv)

apply_update(local_doc, remote_delta)

y_py.apply_update(doc: YDoc, diff: YDocUpdate | List[int])¶

将由远程文档副本生成的增量更新应用于当前文档。此方法假定有效负载保持 lib0 v1 编码格式。

示例:

from y_py import YDoc, encode_state_vector, encode_state_as_update, apply_update

# 机器 A 上的文档
local_doc = YDoc()
local_sv = encode_state_vector(local_doc)

# 机器 B 上的文档
remote_doc = YDoc()
remote_delta = encode_state_as_update(remote_doc, local_sv)

apply_update(local_doc, remote_delta)

class y_py.YTransaction¶

作为文档块存储的代理的事务。Ypy 共享数据类型在给定事务的上下文中执行其操作。每个文档一次只能有一个活动事务——后续尝试将导致异常被抛出。

使用 begin_transaction() 启动的事务可以通过删除事务对象来释放。

示例:

from y_py import YDoc
doc = YDoc()
text = doc.get_text('name')
with doc.begin_transaction() as txn:
    text.insert(txn, 0, 'hello world')

before_state: Dict[int, int]¶

get_text(name: str) → YText¶

返回:: 一个可使用给定 name 进行后续访问的 YText 共享数据类型。

如果之前没有该名称的实例，则会创建并返回它。

如果该名称已有实例，但其类型不同，则会将其投影到 YText 实例上。

get_array(name: str) → YArray¶

返回:: 一个可使用给定 name 进行后续访问的 YArray 共享数据类型。

如果之前没有该名称的实例，则会创建并返回它。

如果该名称已有实例，但其类型不同，则会将其投影到 YArray 实例上。

get_map(name: str) → YMap¶

返回:: 一个可使用给定 name 进行后续访问的 YMap 共享数据类型。

如果之前没有该名称的实例，则会创建并返回它。

如果该名称已有实例，但其类型不同，则会将其投影到 YMap 实例上。

commit()¶: 在不释放事务的情况下触发一系列更新后操作。这包括内部更新表示的压缩和优化，触发事件等。 Ypy 事务在被 free 时自动提交。

state_vector_v1() → EncodedStateVector¶

将给定事务文档的状态向量编码为其二进制表示，使用 lib0 v1 编码。状态向量是对在给定文档上执行的更新的紧凑表示，可以在远程对等体上使用 encode_state_as_update() 生成增量更新有效负载，以同步对等体之间的更改。

示例:

from y_py import YDoc

# 机器 A 上的文档
local_doc = YDoc()
local_txn = local_doc.begin_transaction()

# 机器 B 上的文档
remote_doc = YDoc()
remote_txn = local_doc.begin_transaction()

try:
    local_sv = local_txn.state_vector_v1()
    remote_delta = remote_txn.diff_v1(local_sv)
    local_txn.apply_v1(remote_delta)
finally:
    del local_txn
    del remote_txn

diff_v1(vector: EncodedStateVector | None = None) → YDocUpdate¶

示例:

from y_py import YDoc

# 机器 A 上的文档
local_doc = YDoc()
local_txn = local_doc.begin_transaction()

# 机器 B 上的文档
remote_doc = YDoc()
remote_txn = local_doc.begin_transaction()

try:
    local_sv = local_txn.state_vector_v1()
    remote_delta = remote_txn.diff_v1(local_sv)
    local_txn.apply_v1(remote_delta)
finally:
    del local_txn
    del remote_txn

apply_v1(diff: YDocUpdate)¶

将由远程文档副本生成的增量更新应用于当前事务的文档。此方法假定有效负载保持 lib0 v1 编码格式。

示例:

from y_py import YDoc

# 机器 A 上的文档
local_doc = YDoc()
local_txn = local_doc.begin_transaction()

# 机器 B 上的文档
remote_doc = YDoc()
remote_txn = local_doc.begin_transaction()

try:
    local_sv = local_txn.state_vector_v1()
    remote_delta = remote_txn.diff_v1(local_sv)
    local_txn.apply_v1(remote_delta)
finally:
    del local_txn
    del remote_txn

__enter__() → YTransaction¶

__exit__() → bool¶

class y_py.YText(init: str = '')¶

用于协作文本编辑的共享数据类型。它使多个用户能够高效地添加和删除文本块。此类型在内部表示为能够双向链接的文本块列表——在 YTransaction.commit() 期间会进行优化，允许将多个连续插入的字符压缩为单个文本块，即使在事务边界之间，以保持更高效的内存模型。

YText 结构在内部使用 UTF-8 编码，其长度以字节数而非单个字符表示（单个 UTF-8 码点可以由多个字节组成）。

与所有 Yrs 共享数据类型一样， YText 对交错问题具有抗性（即一个字符后接另一个字符的插入可能与其他对等体的并发插入交错，合并所有更新后）。在 Yrs 中，冲突解决通过使用唯一文档 ID 来确定正确和一致的顺序。

创建一个新的 YText 共享数据类型的初步实例，其状态初始化为提供的参数。

初步实例可以嵌套到其他共享数据类型中，如 YArray 和 YMap。一旦以这种方式插入，便会集成到 Ypy 文档存储中，无法再次嵌套：尝试这样做将导致异常。

prelim: bool¶: 如果该元素尚未集成到 YDoc 中，则为 True 。

__str__() → str¶

返回:: 存储在此数据类型中的底层共享字符串。

__repr__() → str¶

返回:: 用 YText 包装的字符串表示。

__len__() → int¶

返回:: 存储在此 YText 实例中的底层字符串的长度，理解为 UTF-8 编码字节的数量。

to_json() → str¶

返回:: 存储在此数据类型中的底层共享字符串。

insert(txn: YTransaction, index: int, chunk: str, attributes: Dict[str, Any] = {})¶: 在给定的 index 开始位置将一段文本插入到 YText 实例中。属性是可选的样式修饰符（{"bold": True}），可以附加到插入的字符串。属性仅支持已集成到文档存储中的 YText 实例。

insert_embed(txn: YTransaction, index: int, embed: Any, attributes: Dict[str, Any] = {})¶: 在提供的索引位置插入嵌入内容到 YText 中。属性是与嵌入内容相关的用户定义元数据。属性仅支持已集成到文档存储中的 YText 实例。

format(txn: YTransaction, index: int, length: int, attributes: Dict[str, Any])¶: 用包含提供的 attributes 元数据的格式块包装现有文本片段，该片段由 index-length 参数描述。此方法仅对已集成到文档存储中的 YText 实例有效。

extend(txn: YTransaction, chunk: str)¶: 在当前 YText 实例的末尾附加给定的 chunk 文本。

delete(txn: YTransaction, index: int)¶: 删除指定 index 处的字符。

delete_range(txn: YTransaction, index: int, length: int)¶: 删除从给定 index 开始的指定范围内的字符。 index 和 length 的计数以 UTF-8 字节数为单位。

observe(f: Callable[[YTextEvent]]) → SubscriptionId¶

将回调函数分配给监听 YText 更新。

参数:: f -- 当文本对象收到更新时运行的回调函数。
返回:: 对回调订阅的引用。

observe_deep(f: Callable[[List[Event]]]) → SubscriptionId¶

将回调函数分配给监听 YText 实例及其嵌套属性的更新。目前，这将监听与 YText.observe() 相同的事件，但将来也将监听嵌入值的事件。

参数:: f -- 当文本对象或其嵌套属性收到更新时运行的回调函数。
返回:: 对回调订阅的引用。

unobserve(subscription_id: SubscriptionId)¶

取消与 subscription_id 关联的观察者回调。

参数:: subscription_id -- observe() 方法提供的订阅引用。

class y_py.YTextEvent¶

传达在 YText 实例的事务期间发生的更新。 target 引用接收更新的 YText 元素。 delta 是事务应用的更新列表。

target: YText¶

delta: List[YTextDelta]¶

path() → List[int | str]¶

返回:: 从根类型到当前共享类型实例的路径数组（可通过 target 获取器访问）。

y_py.YTextDelta¶

class y_py.YTextChangeInsert¶

Bases: TypedDict

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:: d = {} for k, v in iterable:

d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs: in the keyword argument list. For example: dict(one=1, two=2)

Initialize self. See help(type(self)) for accurate signature.

insert: str¶

attributes: Any | None¶

class y_py.YTextChangeDelete¶

Bases: TypedDict

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:: d = {} for k, v in iterable:

d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs: in the keyword argument list. For example: dict(one=1, two=2)

Initialize self. See help(type(self)) for accurate signature.

delete: int¶

class y_py.YTextChangeRetain¶

Bases: TypedDict

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:: d = {} for k, v in iterable:

d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs: in the keyword argument list. For example: dict(one=1, two=2)

Initialize self. See help(type(self)) for accurate signature.

retain: int¶

attributes: Any | None¶

class y_py.YArray(init: Iterable[Any] | None = None)¶

创建一个新的 YArray 共享数据类型的初步实例，其状态初始化为提供的参数。

初步实例可以嵌套到其他共享数据类型中，如 YArray 和 YMap。一旦初步实例以这种方式插入，它将集成到 Ypy 文档存储中，无法再次嵌套：尝试这样做将导致异常。

prelim: bool¶: 如果该元素尚未集成到 YDoc 中，则为 True。

__len__() → int¶

返回:: YArray 中元素的数量。

__str__() → str¶

返回:: YArray 的字符串表示。

__repr__() → str¶

返回:: 包裹在 YArray 中的 YArray 的字符串表示。

to_json() → str¶: 将此 YArray 实例的底层内容转换为其 JSON 表示。

insert(txn: YTransaction, index: int, item: Any)¶: 在 YArray 中的指定索引处插入一个项。

insert_range(txn: YTransaction, index: int, items: Iterable)¶: 在给定的 index 处将指定范围的 items 插入到此 YArray 实例中。

append(txn: YTransaction, item: Any)¶: 将单个项添加到 YArray 的末尾。

extend(txn: YTransaction, items: Iterable)¶: 将一系列 items 附加到此 YArray 实例的末尾。

delete(txn: YTransaction, index: int)¶

从数组中删除单个项。

参数:

txn -- 正在修改数组的事务。
index -- 要删除的元素的索引。

delete_range(txn: YTransaction, index: int, length: int)¶: 从当前 YArray 实例中删除给定 length 的项范围，从给定的 index 开始。

move_to(txn: YTransaction, source: int, target: int)¶

将在 source 索引处找到的单个项移动到 target 索引位置。

参数:

txn -- 正在修改数组的事务。
source -- 要移动的元素的索引。
target -- 元素的新位置。

move_range_to(txn: YTransaction, start: int, end: int, target: int)¶

将 start..`end` 索引范围内的所有元素（两端均包含）移动到 target 索引指向的新位置。同时插入的其他对等体在移动范围内的元素也将被移动，经过同步后（尽管可能需要多次同步往返才能实现收敛）。

参数:

txn -- 正在修改数组的事务。
start -- 范围第一个元素的索引（包含）。
end -- 范围最后一个元素的索引（包含）。
target -- 元素的新位置。

示例:

import y_py as Y
doc = Y.Doc()
array = doc.get_array('array')

with doc.begin_transaction() as t:
    array.insert_range(t, 0, [1,2,3,4])

# 将元素 2 和 3 移动到 4 之后
with doc.begin_transaction() as t:
    array.move_range_to(t, 1, 2, 4)

__getitem__(index: int | slice) → Any¶

返回:: 存储在给定 index 下的元素或从切片范围生成的新元素列表。

__iter__() → Iterator¶

返回:: 可用于遍历此 YArray 实例中存储的值的迭代器。

示例:

from y_py import YDoc

# 在机器 A 上的文档
doc = YDoc()
array = doc.get_array('name')

for item in array:
    print(item)

observe(f: Callable[[YArrayEvent]]) → SubscriptionId¶

分配一个回调函数以监听 YArray 更新。

参数:: f -- 在数组对象接收到更新时运行的回调函数。
返回:: 与回调订阅相关联的标识符。

observe_deep(f: Callable[[List[Event]]]) → SubscriptionId¶

分配一个回调函数以监听 YArray 及其子元素的聚合更新。

参数:: f -- 在数组对象或组件接收到更新时运行的回调函数。
返回:: 与回调订阅相关联的标识符。

unobserve(subscription_id: SubscriptionId)¶

取消与 subscription_id 相关联的观察者回调。

参数:: subscription_id -- 由 observe() 方法提供的订阅引用。

y_py.YArrayObserver¶

class y_py.YArrayEvent¶

传达在 YArray 实例的事务期间发生的更新。 target: 引用接收更新的 YArray 元素。 delta: 是事务应用的更新列表。

target: YArray¶

delta: List[ArrayDelta]¶

path() → List[int | str]¶

返回:: 从根类型到当前共享类型实例的键和索引数组（通过 target 获取）。

y_py.ArrayDelta¶: 在事务期间对 YArray 的修改。

class y_py.ArrayChangeInsert¶

Bases: TypedDict

更新消息，表示元素已插入到 YArray 中。

Initialize self. See help(type(self)) for accurate signature.

insert: List[Any]¶

class y_py.ArrayChangeDelete¶

更新消息，表示元素已从 YArray 中删除。

delete: int¶

class y_py.ArrayChangeRetain¶

更新消息，表示元素在 YArray 中未修改。

retain: int¶

class y_py.YMap(dict: YMap.__init__.dict)¶

创建一个新的 YMap 共享数据类型的初步实例，其状态初始化为提供的参数。

初步实例可以嵌套到其他共享数据类型中，如 YArray 和 YMap。一旦以这种方式插入初步实例，它将集成到 Ypy 文档存储中，无法再次嵌套：尝试这样做将导致异常。

prelim: bool¶: 如果此元素尚未集成到 YDoc 中，则为 True。

__len__() → int¶

返回:: 此 YMap 实例中存储的条目数量。

__str__() → str¶

返回:: YMap 的字符串表示。

__dict__() → dict¶

返回:: YMap 的内容作为 Python 字典。

__repr__() → str¶

返回:: YMap 的字符串表示，包裹在 'YMap()' 中。

to_json() → str¶: 将此 YMap 实例的内容转换为 JSON 表示。

set(txn: YTransaction, key: str, value: Any)¶: 在此 YMap 实例中设置给定的 key-value 条目。如果已经存在给定 key 的条目，则将其覆盖为新的 value。

update(txn: YTransaction, items: Iterable[Tuple[str, Any]] | Dict[str, Any])¶

使用项目的内容更新 YMap。

参数:

txn -- 执行插入更新的事务。
items -- 生成要插入到 YMap 中的键值元组的可迭代对象。

pop(txn: YTransaction, key: str, fallback: Any | None = None) → Any¶

从此 YMap 实例中移除由给定 key 标识的条目（如果存在）。如果该键不存在且未提供后备值，则抛出 KeyError。

参数:

txn -- 当前 YDoc 的事务。
key -- 请求项目的标识符。
fallback -- 如果 YMap 中不存在该键，则返回该值。

返回:

键对应的项目。

get(key: str, fallback: Any) → Any | None¶

参数:

key -- 请求数据的标识符。
fallback -- 如果该键不存在于映射中，则返回该后备值。

返回:

请求的数据或提供的后备值。

__getitem__(key: str) → Any¶

参数:: key -- 请求数据的标识符。
返回:: 存储在此 YMap 实例中给定 key 下的条目的值。如果提供的键未分配，将抛出 KeyError。

__iter__() → Iterator[str]¶

返回:: 遍历 YMap 所有键的迭代器，顺序不确定。

items() → YMapItemsView¶

返回:: 一个视图，可用于迭代此 YMap 实例中存储的所有条目。条目的顺序未指定。

示例:

from y_py import YDoc

# 机器 A 上的文档
doc = YDoc()
map = doc.get_map('name')
with doc.begin_transaction() as txn:
    map.set(txn, 'key1', 'value1')
    map.set(txn, 'key2', True)
for (key, value) in map.items():
    print(key, value)

keys() → YMapKeysView¶

返回:: YMap 中所有键标识符的视图。键的顺序不稳定。

values() → YMapValuesView¶

返回:: YMap 中所有值的视图。值的顺序不稳定。

observe(f: Callable[[YMapEvent]]) → SubscriptionId¶

分配一个回调函数，以监听 YMap 更新。

参数:: f -- 当映射对象接收更新时运行的回调函数。
返回:: 与回调订阅相关的引用。删除此观察者以擦除关联的回调函数。

observe_deep(f: Callable[[List[Event]]]) → SubscriptionId¶

分配一个回调函数，以监听 YMap 和子元素的更新。

参数:: f -- 当映射对象或其任何跟踪元素接收更新时运行的回调函数。
返回:: 与回调订阅相关的引用。删除此观察者以擦除关联的回调函数。

unobserve(subscription_id: SubscriptionId)¶

取消与 subscription_id 相关的观察者回调。

参数:: subscription_id -- 由 observe() 方法提供的订阅引用。

class y_py.YMapItemsView¶

跟踪 YMap 内的键/值。类似于 Python 字典的 dict_items 功能。

__iter__() → Iterator[Tuple[str, Any]]¶: 生成视图内元素的键值元组。

__contains__(item: Tuple[str, Any]) → bool¶: 检查键值元组是否在视图中。

__len__() → int¶: 检查视图中的项目数量。

class y_py.YMapKeysView¶

跟踪 YMap 内的键标识符。

__iter__() → Iterator[str]¶: 生成视图的键。

__contains__(key: str) → bool¶: 检查键是否在视图中。

__len__() → int¶: 检查视图中的键数量。

class y_py.YMapValuesView¶

跟踪 YMap 内的值。

__iter__() → Iterator[Any]¶: 生成视图的值。

__contains__(value: Any) → bool¶: 检查值是否在视图中。

__len__() → int¶: 检查视图中的值数量。

class y_py.YMapEvent¶

通信在 YMap 实例的事务期间发生的更新。 target 引用接收更新的 YMap 元素。 delta 是事务应用的更新列表。 keys 是特定键的更改值列表。

target: YMap¶: 在此事件中修改的元素。

keys: Dict[str, YMapEventKeyChange]¶: 按键对 YMap 的修改列表。包括修改类型以及修改前后的状态。

path() → List[int | str]¶

返回:: 如果此 YMap 嵌套在另一个数据结构中，则从根到此元素的路径。

class y_py.YMapEventKeyChange¶

Bases: TypedDict

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:: d = {} for k, v in iterable:

d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs: in the keyword argument list. For example: dict(one=1, two=2)

Initialize self. See help(type(self)) for accurate signature.

action: Literal['add', 'update', 'delete']¶

oldValue: Any | None¶

newValue: Any | None¶

y_py.YXmlAttributes¶: 生成 XML 元素的键/值属性序列。

y_py.Xml¶

y_py.YXmlTreeWalker¶: 访问 XML 树中的元素。

y_py.EntryChange¶

class y_py.YXmlElementEvent¶

target: YXmlElement¶

keys: Dict[str, EntryChange]¶

delta: List[Dict]¶

path() → List[int | str]¶: 返回当前共享类型实例，当前事件更改所指。

class y_py.YXmlElement¶

XML 元素数据类型。它表示一个 XML 节点，可以包含键值属性（解释为字符串），以及其他嵌套的 XML 元素或富文本（由 YXmlText 类型表示）。

在冲突解决方面，YXmlElement 使用以下规则：

属性更新使用逻辑的最后写入优先原则，意味着过去的更新会被新的更新自动覆盖并丢弃，而不同节点的并发更新将通过文档 ID 的优先级来建立顺序，解析为单个值。
子节点插入使用其他 Yrs 集合的序列化规则——元素通过抗交错算法插入，在相同索引的并发插入顺序通过节点的文档 ID 优先级来建立。

name: str¶

first_child: Xml | None¶

next_sibling: Xml | None¶

prev_sibling: Xml | None¶

parent: YXmlElement | None¶

__len__() → int¶: 返回此 YXmlElement 实例中存储的子 XML 节点数量。

insert_xml_element(txn: YTransaction, index: int, name: str) → YXmlElement¶: 将一个新的 YXmlElement 实例作为此 XML 节点的子节点插入并返回它。

insert_xml_text(txn: YTransaction, index: int) → YXmlText¶: 将一个新的 YXmlText 实例作为此 XML 节点的子节点插入并返回它。

delete(txn: YTransaction, index: int, length: int)¶: 从此 YXmlElement 实例中移除一范围的子 XML 节点，从给定的 index 开始。

push_xml_element(txn: YTransaction, name: str) → YXmlElement¶: 将一个新的 YXmlElement 实例附加为此 XML 节点的最后一个子节点并返回它。

push_xml_text(txn: YTransaction) → YXmlText¶: 将一个新的 YXmlText 实例附加为此 XML 节点的最后一个子节点并返回它。

__str__() → str¶

返回:: 此 XML 节点的字符串表示。

__repr__() → str¶

返回:: 用 YXmlElement 包裹的字符串表示。

set_attribute(txn: YTransaction, name: str, value: str)¶: 将 name 和 value 设置为此 XML 节点的新属性。如果节点上已存在同名的属性，其值将被提供的值覆盖。

get_attribute(name: str) → str | None¶

返回:: 返回给定 name 的属性值。如果没有该名称的属性，将返回 null 。

remove_attribute(txn: YTransaction, name: str)¶: 根据其 name 从此 XML 节点移除一个属性。

attributes() → YXmlAttributes¶

返回:: 返回一个迭代器，使其能够以未指定的顺序遍历此 XML 节点的所有属性。

tree_walker() → YXmlTreeWalker¶

返回:: 返回一个迭代器，使其能够对该 XML 节点进行深度遍历—— 从第一个子节点开始，使用深度优先策略遍历此 XML 节点的后续节点。

observe(f: Callable[[YXmlElementEvent]]) → SubscriptionId¶

订阅对此 YXmlElement 实例发生的所有操作。所有更改被批处理，并在事务提交阶段最终触发。

参数:: f -- 接收更新事件的回调函数。
返回:: 可用于取消观察者回调的 SubscriptionId。

observe_deep(f: Callable[[List[Event]]]) → SubscriptionId¶

订阅对此 YXmlElement 实例及其子节点发生的所有操作。所有更改被批处理，并在事务提交阶段最终触发。

参数:: f -- 接收 XML 元素及其子元素更新事件的回调函数。
返回:: 可用于取消观察者回调的 SubscriptionId。

unobserve(subscription_id: SubscriptionId)¶

取消与 subscription_id 相关的观察者回调。

参数:: subscription_id -- YXmlElement:observe() 方法提供的订阅引用。

class y_py.YXmlFragment¶

XML 片段数据类型。它表示一组 XML 节点。

first_child: Xml | None¶

parent: YXmlElement | None¶

__len__() → int¶: 返回此 YXmlFragment 实例中存储的子 XML 节点数量。

insert_xml_element(txn: YTransaction, index: int, name: str) → YXmlElement¶: 将一个新的 YXmlElement 实例作为此 XML 片段的子节点插入并返回它。

insert_xml_text(txn: YTransaction, index: int) → YXmlText¶: 将一个新的 YXmlText 实例作为此 XML 片段的子节点插入并返回它。

delete(txn: YTransaction, index: int, length: int)¶: 从此 YXmlFragment 实例中移除一范围的子 XML 节点，从给定的 index 开始。

push_xml_element(txn: YTransaction, name: str) → YXmlElement¶: 将一个新的 YXmlElement 实例附加为此 XML 片段的最后一个子节点并返回它。

push_xml_text(txn: YTransaction) → YXmlText¶: 将一个新的 YXmlText 实例附加为此 XML 片段的最后一个子节点并返回它。

__str__() → str¶

返回:: 此 XML 片段的字符串表示。

__repr__() → str¶

返回:: 此 YXmlFragment 的字符串表示。

get(index: int) → YXmlText | YXmlElement¶: 返回指定索引处的子节点。

tree_walker() → YXmlTreeWalker¶: 返回一个迭代器，使其能够对该 XML 片段进行深度遍历—— 从第一个子节点开始，使用深度优先策略遍历此 XML 片段的后续节点。

observe(f: Callable[[YXmlElementEvent]]) → SubscriptionId¶

订阅对此 YXmlFragment 实例发生的所有操作。所有更改被批处理，并在事务提交阶段最终触发。

参数:: f -- 接收更新事件的回调函数。
返回:: 可用于取消观察者回调的 SubscriptionId。

observe_deep(f: Callable[[List[Event]]]) → SubscriptionId¶

订阅对此 YXmlFragment 实例及其子节点发生的所有操作。所有更改被批处理，并在事务提交阶段最终触发。

参数:: f -- 接收 XML 片段及其子元素更新事件的回调函数。
返回:: 可用于取消观察者回调的 SubscriptionId。

unobserve(subscription_id: SubscriptionId)¶

取消与 subscription_id 相关的观察者回调。

参数:: subscription_id -- observe() 方法提供的订阅引用。

class y_py.YXmlText¶

next_sibling: Xml | None¶

prev_sibling: Xml | None¶

parent: YXmlElement | None¶

__len__()¶

返回:: 此 YXmlText 实例中存储的底层字符串的长度，以 UTF-8 编码字节数表示。

insert(txn: YTransaction, index: int, chunk: str)¶: 将给定的 chunk 文本插入到此 YXmlText 实例中，从给定的 index 开始。

push(txn: YTransaction, chunk: str)¶: 将给定的 chunk 文本附加到 YXmlText 实例的末尾。

delete(txn: YTransaction, index: int, length: int)¶: 删除从给定 index 开始的指定范围的字符。 index 和 length 都以 UTF-8 字符字节数为单位进行计数。

__str__() → str¶

返回:: 此 YXmlText 实例中存储的底层字符串。

__repr__() → str¶

返回:: 用 'YXmlText()' 包裹的字符串表示。

set_attribute(txn: YTransaction, name: str, value: str)¶: 将 name 和 value 作为此 XML 节点的新属性设置。如果该节点上已经存在相同 name 的属性，则其值将被提供的值覆盖。

get_attribute(name: str) → str | None¶

返回:: 给定 name 的属性值。如果不存在该名称的属性，将返回 None。

remove_attribute(txn: YTransaction, name: str)¶: 从此 XML 节点中移除给定 name 的属性。

attributes() → YXmlAttributes¶

返回:: 一个迭代器，使其能够以不指定顺序遍历此 XML 节点的所有属性。

observe(f: Callable[[YXmlTextEvent]]) → SubscriptionId¶

订阅对此 YXmlText 实例发生的所有操作。所有更改被批处理，并在事务提交阶段最终触发。

参数:: f: 接收更新事件的回调函数。

返回:: 可用于取消观察者回调的 SubscriptionId。

observe_deep(f: Callable[[List[Event]]]) → SubscriptionId¶

订阅对此 YXmlText 实例及其子元素发生的所有操作。所有更改被批处理，并在事务提交阶段最终触发。

参数:: f: 接收此元素及其后代更新事件的回调函数。

返回:: 可用于取消观察者回调的 SubscriptionId。

unobserve(subscription_id: SubscriptionId)¶

取消与 subscription_id 相关的观察者回调。

参数:: subscription_id -- observe() 方法提供的订阅引用。

class y_py.YXmlTextEvent¶

target: YXmlText¶

keys: List[EntryChange]¶

delta: List[YTextDelta]¶

path() → List[int | str]¶: 返回当前事件更改所指的当前共享类型实例。