API reference

Array

Bases: BaseType

A collection used to store data in an indexed sequence structure, similar to a Python list.

doc: Doc property

The document this shared type belongs to.

Raises:

Type	Description
RuntimeError	Not integrated in a document yet.

__add__(value)

Extends the array with a list of items:

Doc()["array"] = array = Array(["foo"])
array += ["bar", "baz"]
assert array.to_py() == ["foo", "bar", "baz"]

Parameters:

Name	Type	Description	Default
value	list[Any]	The items that will extend the array.	required

Returns:

Type	Description
Array	The extended array.

__contains__(item)

Checks if the given item is in the array:

Doc()["array"] = array = Array(["foo", "bar"])
assert "baz" not in array

Parameters:

Name	Type	Description	Default
item	Any	The item to look for in the array.	required

Returns:

Type	Description
bool	True if the item was found.

__delitem__(key)

Removes the item at the given index from the array:

Doc()["array"] = array = Array(["foo", "bar", "baz"])
del array[2]
assert array.to_py() == ["foo", "bar"]

Parameters:

Name	Type	Description	Default
key	int | slice	The index of the item to remove.	required

Raises:

Type	Description
RuntimeError	Array indices must be integers or slices.

__getitem__(key)

Gets the item at the given index:

Doc()["array"] = array = Array(["foo", "bar", "baz"])
assert array[1] == "bar"

Returns:

Type	Description
BaseType	The item at the given index.

__init__(init=None, *, _doc=None, _integrated=None)

Creates an array with an optional initial value:

array0 = Array()
array1 = Array(["foo", 3, array0])

Parameters:

Name	Type	Description	Default
init	list | None	The list from which to initialize the array.	None

__iter__()

Doc()["array"] = array = Array(["foo", "foo"])
for value in array:
    assert value == "foo"

Returns: An iterable over the items of the array.

__len__()

Doc()["array"] = array = Array([2, 3, 0])
assert len(array) == 3

Returns:

Type	Description
int	The length of the array.

__radd__(value)

Prepends a list of items to the array:

Doc()["array"] = array = Array(["bar", "baz"])
array = ["foo"] + array
assert array.to_py() == ["foo", "bar", "baz"]

Parameters:

Name	Type	Description	Default
value	list[Any]	The list of items to prepend.	required

Returns:

Type	Description
Array	The prepended array.

__setitem__(key, value)

Replaces the item at the given index with a new item:

Doc()["array"] = array = Array(["foo", "bar"])
array[1] = "baz"
assert array.to_py() == ["foo", "baz"]

Parameters:

Name	Type	Description	Default
key	int | slice	The index of the item to replace.	required
value	Any | list[Any]	The new item to set.	required

Raises:

Type	Description
RuntimeError	Index must be of type integer.

__str__()

Doc()["array"] = array = Array([2, 3, 0])
assert str(array) == "[2,3,0]"

Returns:

Type	Description
str	The string representation of the array.

append(value)

Appends an item to the array.

Parameters:

Name	Type	Description	Default
value	Any	The item to append to the array.	required

clear()

Removes all items from the array.

extend(value)

Extends the array with a list of items.

Parameters:

Name	Type	Description	Default
value	list[Any]	The items that will extend the array.	required

insert(index, object)

Inserts an item at a given index in the array.

Parameters:

Name	Type	Description	Default
index	int	The index where to insert the item.	required
object	Any	The item to insert in the array.	required

move(source_index, destination_index)

Moves an item in the array from a source index to a destination index.

Parameters:

Name	Type	Description	Default
source_index	int	The index of the item to move.	required
destination_index	int	The index where the item will be inserted.	required

observe(callback)

Subscribes a callback to be called with the array event.

Parameters:

Name	Type	Description	Default
callback	Callable[[ArrayEvent], None]	The callback to call with the ArrayEvent.	required

observe_deep(callback)

Subscribes a callback for all events emitted by this and nested collaborative types.

Parameters:

Name	Type	Description	Default
callback	Callable[[list[BaseEvent]], None]	The callback to call with the list of events.	required

pop(index=-1)

Removes the item at the given index from the array, and returns it. If no index is passed, removes and returns the last item.

Parameters:

Name	Type	Description	Default
index	int	The optional index of the item to pop.	-1

Returns:

Type	Description
Any	The item at the given index, or the last item.

to_py()

Recursively converts the array's items to Python objects, and returns them in a list. If the array was not yet inserted in a document, returns None if the array was not initialized.

Returns:

Type	Description
list | None	The array recursively converted to Python objects, or None.

unobserve(subscription)

Unsubscribes to changes using the given subscription.

Parameters:

Name	Type	Description	Default
subscription	Subscription	The subscription to unregister.	required

ArrayEvent

Bases: BaseEvent

An array change event.

Attributes:

Name	Type	Description
target	Array	The changed array.
delta	list[dict[str, Any]]	A list of items describing the changes.
path	list[int | str]	A list with the indices pointing to the array that was changed.

Awareness

meta: dict[int, dict[str, Any]] property

The clients' metadata.

states: dict[int, dict[str, Any]] property

The client states.

__init__(ydoc, *, outdated_timeout=30000)

Parameters:

Name	Type	Description	Default
ydoc	Doc	The Doc to associate the awareness with.	required
outdated_timeout	int	The timeout (in milliseconds) to consider a client gone.	30000

apply_awareness_update(update, origin)

Applies the binary update and notifies subscribers with changes.

Parameters:

Name	Type	Description	Default
update	bytes	The binary update.	required
origin	Any	The origin of the update.	required

encode_awareness_update(client_ids)

Creates an encoded awareness update of the clients given by their IDs.

Parameters:

Name	Type	Description	Default
client_ids	list[int]	The list of client IDs for which to create an update.	required

Returns:

Type	Description
bytes	The encoded awareness update.

get_local_state()

Returns:

Type	Description
dict[str, Any] | None	The local state, if any.

observe(callback)

Registers the given callback to awareness changes.

Parameters:

Name	Type	Description	Default
callback	Callable[[str, tuple[dict[str, Any], Any]], None]	The callback to call with the awareness changes.	required

Returns:

Type	Description
str	The subscription ID that can be used to unobserve.

remove_awareness_states(client_ids, origin)

Removes awareness states for clients given by their IDs.

Parameters:

Name	Type	Description	Default
client_ids	list[int]	The list of client IDs for which to remove the awareness states.	required
origin	Any	The origin of the update.	required

set_local_state(state)

Updates the local state and meta, and sends the changes to subscribers.

Parameters:

Name	Type	Description	Default
state	dict[str, Any] | None	The new local state, if any.	required

set_local_state_field(field, value)

Sets a local state field.

Parameters:

Name	Type	Description	Default
field	str	The field of the local state to set.	required
value	Any	The value associated with the field.	required

start(*, task_status=TASK_STATUS_IGNORED) async

Starts updating the awareness periodically.

stop() async

Stops updating the awareness periodically.

unobserve(id)

Unregisters the given subscription ID from awareness changes.

Parameters:

Name	Type	Description	Default
id	str	The subscription ID to unregister.	required

Decoder

A decoder capable of reading messages from a byte stream.

__init__(stream)

Parameters:

Name	Type	Description	Default
stream	bytes	The byte stream from which to read messages.	required

read_message()

Reads a message from the byte stream, ready to read the next message if any.

Returns:

Type	Description
bytes | None	The current message, if any.

read_messages()

A generator that reads messages from the byte stream.

Returns:

Type	Description
Iterator[bytes]	A generator that yields messages.

read_var_string()

Reads a message as an UTF-8 string from the byte stream, ready to read the next message if any.

Returns:

Type	Description
str	The current message as a string.

read_var_uint()

Decodes the current message length.

Returns:

Type	Description
int	The decoded length of the message.

Doc

Bases: BaseDoc

A shared document.

All shared types live within the scope of their corresponding documents. All updates are generated on a per-document basis. All operations on shared types happen in a transaction, whose lifetime is also bound to a document.

client_id: int property

The document client ID.

guid: int property

The GUID of the document.

__getitem__(key)

Gets the document root type corresponding to the given key:

text = doc["text"]

Parameters:

Name	Type	Description	Default
key	str	The key of the root type to get.	required

Returns:

Type	Description
BaseType	The document root type.

__init__(init={}, *, client_id=None, doc=None, Model=None, allow_multithreading=False)

Parameters:

Name	Type	Description	Default
init	dict[str, BaseType]	The initial root types of the document.	{}
client_id	int | None	An optional client ID for the document.	None
allow_multithreading	bool	Whether to allow the document to be used in different threads.	False

__iter__()

Returns:

Type	Description
Iterable[str]	An iterable over the keys of the document root types.

__setitem__(key, value)

Sets a document root type:

doc["text"] = Text("Hello")

Parameters:

Name	Type	Description	Default
key	str	The name of the root type.	required
value	BaseType	The root type.	required

Raises:

Type	Description
RuntimeError	Key must be of type string.

apply_update(update)

Parameters:

Name	Type	Description	Default
update	bytes	The update to apply to the document.	required

get(key, *, type)

Gets the document root type corresponding to the given key. If it already exists, it will be cast to the given type (if different), otherwise a new root type is created.

doc.get("text", type=Text)

Returns:

Type	Description
T_BaseType	The root type corresponding to the given key, cast to the given type.

get_state()

Returns:

Type	Description
bytes	The current document state.

get_update(state=None)

Parameters:

Name	Type	Description	Default
state	bytes | None	The optional document state from which to get the update.	None

Returns:

Type	Description
bytes	The update from the given document state (if any), or from the document creation.

items()

Returns:

Type	Description
Iterable[tuple[str, BaseType]]	An iterable over the key-value pairs of document root types.

keys()

Returns:

Type	Description
Iterable[str]	An iterable over the names of the document root types.

new_transaction(origin=None, timeout=None)

Creates a new transaction. Unlike transaction(), this method will not reuse an ongoing transaction. If there is already an ongoing transaction, this method will wait (with an optional timeout) until the current transaction has finished. There are two ways to do so:

• Use an async context manager:

  async with doc.new_transaction():
      ...
  

  In this case you most likely access the document in the same thread, which means that the Doc can be created with allow_multithreading=False.

• Use a (sync) context manager:

  with doc.new_transaction():
      ...
  

  In this case you want to use multithreading, as the ongoing transaction must run in another thread (otherwise this will deadlock), which means that the Doc must have been created with allow_multithreading=True.

Parameters:

Name	Type	Description	Default
origin	Any	An optional origin to set on this transaction.	None
timeout	float | None	An optional timeout (in seconds) to acquire a new transaction.	None

Raises:

Type	Description
RuntimeError	Already in a transaction.
TimeoutError	Could not acquire transaction.

Returns:

Type	Description
NewTransaction	A new transaction.

observe(callback)

Subscribes a callback to be called with the document change event.

Parameters:

Name	Type	Description	Default
callback	Callable[[TransactionEvent], None]	The callback to call with the TransactionEvent.	required

Returns:

Type	Description
Subscription	The subscription that can be used to unobserve().

observe_subdocs(callback)

Subscribes a callback to be called with the document subdoc change event.

Parameters:

Name	Type	Description	Default
callback	Callable[[SubdocsEvent], None]	The callback to call with the SubdocsEvent.	required

Returns:

Type	Description
Subscription	The subscription that can be used to unobserve().

transaction(origin=None)

Creates a new transaction or gets the current one, if any. If an origin is passed and there is already an ongoing transaction, the passed origin must be the same as the origin of the current transaction.

This method must be used with a context manager:

with doc.transaction():
    ...

Parameters:

Name	Type	Description	Default
origin	Any	An optional origin to set on this transaction.	None

Raises:

Type	Description
RuntimeError	Nested transactions must have same origin as root transaction.

Returns:

Type	Description
Transaction	A new transaction or the current one.

unobserve(subscription)

Unsubscribes to changes using the given subscription.

Parameters:

Name	Type	Description	Default
subscription	Subscription	The subscription to unregister.	required

values()

Returns:

Type	Description
Iterable[BaseType]	An iterable over the document root types.

Encoder

An encoder capable of writing messages to a binary stream.

to_bytes()

Returns:

Type	Description
bytes	The binary stream.

write_var_string(text)

Encodes a string.

Parameters:

Name	Type	Description	Default
text	str	The string to encode.	required

write_var_uint(num)

Encodes a number.

Parameters:

Name	Type	Description	Default
num	int	The number to encode.	required

Map

Bases: BaseType

A collection used to store key-value entries in an unordered manner, similar to a Python dict.

doc: Doc property

The document this shared type belongs to.

Raises:

Type	Description
RuntimeError	Not integrated in a document yet.

__contains__(item)

Checks if the given key is in the map:

Doc()["map0"] = map0 = Map({"foo": 0, "bar": 0})
assert "baz" not in map0:

Parameters:

Name	Type	Description	Default
item	str	The key to look for in the map.	required

Returns:

Type	Description
bool	True if the key was found.

__delitem__(key)

Removes the item at the given key from the map:

Doc()["map0"] = map0 = Map({"foo": 0, "bar": 1})
del map0["foo"]
assert map0.to_py() == {"bar": 1}

Parameters:

Name	Type	Description	Default
key	str	The key of the item to remove.	required

__getitem__(key)

Gets the value at the given key:

Doc()["map0"] = map0 = Map({"foo": 0, "bar": 1})
assert map0["foo"] == 0

Returns:

Type	Description
Any	The value at the given key.

__init__(init=None, *, _doc=None, _integrated=None)

Creates a map with an optional initial value:

map0 = Map()
map1 = Map({"foo": 0, "bar": 3, "baz": map0})

Parameters:

Name	Type	Description	Default
init	dict | None	The list from which to initialize the array.	None

__iter__()

Doc()["map0"] = map0 = Map({"foo": 0, "bar": 0})
for key in m0:
    assert map[key] == 0

Returns: An iterable over the keys of the map.

__len__()

Doc()["map0"] = map0 = Map({"foo": 0, "bar": 1})
assert len(map0) == 2

Returns: The length of the map.

__setitem__(key, value)

Sets a value at the given key:

Doc()["map0"] = map0 = Map({"foo": 0, "bar": 1})
map0["foo"] = 2
assert map0["foo"] == 2

Parameters:

Name	Type	Description	Default
key	str	The key to set.	required
value	Any	The value to set.	required

Raises:

Type	Description
RuntimeError	Key must be of type string.

__str__()

Doc()["map0"] = map0 = Map({"foo": 0, "bar": 1})
assert str(map0) == '{"foo":0,"bar":1}'

Returns:

Type	Description
str	The string representation of the map.

clear()

Removes all entries from the map.

get(key, default_value=None)

Returns the value corresponding to the given key if it exists, otherwise returns the default_value.

Parameters:

Name	Type	Description	Default
key	str	The key of the value to get.	required
default_value	Any | None	The optional default value to return if the key is not found.	None

Returns:

Type	Description
Any | None	The value at the given key, or the default value.

items()

Returns:

Type	Description
Iterable[tuple[str, Any]]	An iterable over the key-value pairs of the map.

keys()

Returns:

Type	Description
Iterable[str]	An iterable over the keys of the map.

observe(callback)

Subscribes a callback to be called with the map event.

Parameters:

Name	Type	Description	Default
callback	Callable[[MapEvent], None]	The callback to call with the MapEvent.	required

observe_deep(callback)

Subscribes a callback for all events emitted by this and nested collaborative types.

Parameters:

Name	Type	Description	Default
callback	Callable[[list[BaseEvent]], None]	The callback to call with the list of events.	required

pop(*args)

Removes the entry at the given key from the map, and returns the corresponding value.

Parameters:

Name	Type	Description	Default
args	Any	The key of the value to pop, and an optional default value.	()

Returns:

Type	Description
Any	The value at the given key, or the default value if passed.

to_py()

Recursively converts the map's items to Python objects, and returns them in a dict. If the map was not yet inserted in a document, returns None if the map was not initialized.

Returns:

Type	Description
dict | None	The map recursively converted to Python objects, or None.

unobserve(subscription)

Unsubscribes to changes using the given subscription.

Parameters:

Name	Type	Description	Default
subscription	Subscription	The subscription to unregister.	required

update(value)

Sets entries in the map from all entries in the passed dict.

Parameters:

Name	Type	Description	Default
value	dict[str, Any]	The dict from which to get the entries to update.	required

values()

Returns:

Type	Description
Iterable[Any]	An iterable over the values of the map.

MapEvent

Bases: BaseEvent

A map change event.

Attributes:

Name	Type	Description
target	Map	The changed map.
delta	list[dict[str, Any]]	A list of items describing the changes.
path	list[int | str]	A list with the indices pointing to the map that was changed.

NewTransaction

Bases: Transaction

A read-write transaction that can be used to mutate a document. It can be used with a context manager or an async context manager (see Doc.new_transaction()):

with doc.new_transaction():
    ...

async with doc.new_transaction():
    ...

origin: Any property

The origin of the transaction.

Raises:

Type	Description
RuntimeError	No current transaction.

ReadTransaction

Bases: Transaction

A read-only transaction that cannot be used to mutate a document.

origin: Any property

The origin of the transaction.

Raises:

Type	Description
RuntimeError	No current transaction.

StackItem

A unit of work for the UndoManager, consisting of compressed information about all updates and deletions tracked by it.

Subscription

Observer subscription.

drop()

Drops the subscription, effectively unobserving.

SubdocsEvent

Event generated by the observe_subdocs method, emitted during the transaction commit phase.

Text

Bases: BaseType

A shared data type used for collaborative text editing, similar to a Python str.

doc: Doc property

The document this shared type belongs to.

Raises:

Type	Description
RuntimeError	Not integrated in a document yet.

__contains__(item)

Checks if the given string is in the text:

Doc()["text"] = text = Text("Hello, World!")
assert "World" in text

Parameters:

Name	Type	Description	Default
item	str	The string to look for in the text.	required

Returns:

Type	Description
bool	True if the string was found.

__delitem__(key)

Removes the characters at the given index or slice:

Doc()["text"] = text = Text("Hello, World!")
del text[5]
assert str(text) == "Hello World!"
del text[5:]
assert str(text) == "Hello"

Parameters:

Name	Type	Description	Default
key	int | slice	The index or the slice of the characters to remove.	required

Raises:

Type	Description
RuntimeError	Step not supported.
RuntimeError	Negative start not supported.
RuntimeError	Negative stop not supported.

__getitem__(key)

Gets the characters at the given index or slice:

Doc()["text"] = text = Text("Hello, World!")
assert text[:5] == "Hello"

Returns:

Type	Description
str	The characters at the given index or slice.

__iadd__(value)

Concatenates a string to the text:

Doc()["text"] = text = Text("Hello")
text += ", World!"
assert str(text) == "Hello, World!"

Parameters:

Name	Type	Description	Default
value	str	The string to concatenate.	required

Returns:

Type	Description
Text	The concatenated text.

__init__(init=None, *, _doc=None, _integrated=None)

Creates a text with an optional initial value:

text = Text("Hello, World!")

Parameters:

Name	Type	Description	Default
init	str | None	The string from which to initialize the text.	None

__iter__()

Doc()["text"] = text = Text("***")
for character in text:
    assert character == "*"

Returns:

Type	Description
TextIterator	An iterable over the characters of the text.

__len__()

Doc()["text"] = text = Text("Hello")
assert len(text) == 5

Returns:

Type	Description
int	The length of the text.

__setitem__(key, value)

Replaces the characters at the given index or slice with new characters:

Doc()["text"] = text = Text("Hello, World!")
text[7:12] = "Brian"
assert text == "Hello, Brian!"

Parameters:

Name	Type	Description	Default
key	int | slice	The index or slice of the characters to replace.	required
value	str	The new characters to set.	required

Raises:

Type	Description
RuntimeError	Step not supported.
RuntimeError	Negative start not supported.
RuntimeError	Negative stop not supported.
RuntimeError	Single item assigned value must have a length of 1.

__str__()

Returns:

Type	Description
str	The text as a Python str.

clear()

Remove the entire range of characters.

diff()

Returns:

Type	Description
list[tuple[Any, dict[str, Any] | None]]	A list of formatted chunks that the current text corresponds to. Each list item is a tuple containing the chunk's content and formatting attributes. The content is usually the text as a string, but may be other data for embedded objects.

format(start, stop, attrs)

Applies formatting attributes to a section of text between given start and stop indices.

Parameters:

Name	Type	Description	Default
start	int	The index at which to start applying attributes (included).	required
stop	int	The index at which to stop applying attributes (excluded).	required
attrs	dict[str, Any]	The formatting attributes to apply.	required

insert(index, value, attrs=None)

Inserts a string at a given index in the text, with optional attributes.

Doc()["text"] = text = Text("Hello World!")
text.insert(5, ",")
assert text == "Hello, World!"

Parameters:

Name	Type	Description	Default
index	int	The index where to insert the string.	required
value	str	The string to insert in the text.	required
attrs	dict[str, Any] | None	The formatting of attributes to apply.	None

insert_embed(index, value, attrs=None)

Insert a value as an embed at a given index in the text, with optional attributes.

Parameters:

Name	Type	Description	Default
index	int	The index where to insert the embedded content.	required
value	Any	The value to embed.	required
attrs	dict[str, Any] | None	The formatting attributes to apply.	None

observe(callback)

Subscribes a callback to be called with the text event.

Parameters:

Name	Type	Description	Default
callback	Callable[[TextEvent], None]	The callback to call with the TextEvent.	required

observe_deep(callback)

Subscribes a callback for all events emitted by this and nested collaborative types.

Parameters:

Name	Type	Description	Default
callback	Callable[[list[BaseEvent]], None]	The callback to call with the list of events.	required

to_py()

Returns:

Type	Description
str | None	The text as a Python str.

unobserve(subscription)

Unsubscribes to changes using the given subscription.

Parameters:

Name	Type	Description	Default
subscription	Subscription	The subscription to unregister.	required

TextEvent

Bases: BaseEvent

A text change event.

Attributes:

Name	Type	Description
target	Text	The changed text.
delta	list[dict[str, Any]]	A list of items describing the changes.
path	list[int | str]	A list with the indices pointing to the text that was changed.

Transaction

A read-write transaction that can be used to mutate a document. It must be used with a context manager (see Doc.transaction()):

with doc.transaction():
    ...

origin: Any property

The origin of the transaction.

Raises:

Type	Description
RuntimeError	No current transaction.

TransactionEvent

Event generated by the observe method, emitted during the transaction commit phase.

update: bytes property

The emitted binary update.

UndoManager

The undo manager allows to perform undo/redo operations on shared types. It can be initialized either with a Doc or with scopes. Scopes are a list of shared types integrated in a document. If initialized with a Doc, scopes can later be expanded. Changes can be undone/redone by batches using time intervals. It is possible to include/exclude changes by transaction origin in undo/redo operations.

redo_stack: list[StackItem] property

The list of redoable actions.

undo_stack: list[StackItem] property

The list of undoable actions.

__init__(*, doc=None, scopes=[], capture_timeout_millis=500)

Parameters:

Name	Type	Description	Default
doc	Doc | None	The document the undo manager will work with.	None
scopes	list[BaseType]	A list of shared types the undo manager will work with.	[]
capture_timeout_millis	int	A time interval for grouping changes that will be undone/redone.	500

Raises:

Type	Description
RuntimeError	UndoManager must be created with doc or scopes.

can_redo()

Returns:

Type	Description
bool	True if there are changes to redo.

can_undo()

Returns:

Type	Description
bool	True if there are changes to undo.

clear()

Clears all StackItems stored in this undo manager, effectively resetting its state.

exclude_origin(origin)

Removes a transaction origin from the list of origins tracked by this undo manager.

Parameters:

Name	Type	Description	Default
origin	Any	The origin to exclude.	required

expand_scope(scope)

Expands the scope of shared types for this undo manager.

Parameters:

Name	Type	Description	Default
scope	BaseType	The shared type to include.	required

include_origin(origin)

Extends the list of transactions origin tracked by this undo manager.

Parameters:

Name	Type	Description	Default
origin	Any	The origin to include.	required

redo()

Perform a redo operation.

Returns:

Type	Description
bool	True if some changes were redone.

undo()

Perform an undo operation.

Returns:

Type	Description
bool	True if some changes were undone.

XmlElement

Bases: _XmlFragmentTraitMixin, _XmlTraitMixin

attributes: XmlAttributesView property

A dict-like view into this object's attributes.

children: XmlChildrenView property

A list-like view into this object's child nodes.

doc: Doc property

The document this shared type belongs to.

Raises:

Type	Description
RuntimeError	Not integrated in a document yet.

parent: XmlFragment | XmlElement | XmlText | None property

The parent of this node, if any.

tag: str | None property

The element's tag, if any.

__init__(tag=None, attributes=None, contents=None, *, _doc=None, _integrated=None)

Creates an XML element.

Parameters:

Name	Type	Description	Default
tag	str | None	The tag of the element (required).	None
attributes	dict[str, str] | Iterable[tuple[str, str]] | None	The optional attributes of the element.	None
contents	Iterable[XmlFragment | XmlElement | XmlText] | None	The optional contents of the element.	None

observe_deep(callback)

Subscribes a callback for all events emitted by this and nested collaborative types.

Parameters:

Name	Type	Description	Default
callback	Callable[[list[BaseEvent]], None]	The callback to call with the list of events.	required

unobserve(subscription)

Unsubscribes to changes using the given subscription.

Parameters:

Name	Type	Description	Default
subscription	Subscription	The subscription to unregister.	required

XmlFragment

Bases: _XmlFragmentTraitMixin

children: XmlChildrenView property

A list-like view into this object's child nodes.

doc: Doc property

The document this shared type belongs to.

Raises:

Type	Description
RuntimeError	Not integrated in a document yet.

parent: XmlFragment | XmlElement | XmlText | None property

The parent of this node, if any.

observe_deep(callback)

Subscribes a callback for all events emitted by this and nested collaborative types.

Parameters:

Name	Type	Description	Default
callback	Callable[[list[BaseEvent]], None]	The callback to call with the list of events.	required

unobserve(subscription)

Unsubscribes to changes using the given subscription.

Parameters:

Name	Type	Description	Default
subscription	Subscription	The subscription to unregister.	required

XmlText

Bases: _XmlTraitMixin

A piece of text in an XML tree.

This is similar to a Text, but instead of existing in a Doc on its own, it is a child of XmlElement or XmlFragment.

attributes: XmlAttributesView property

A dict-like view into this object's attributes.

doc: Doc property

The document this shared type belongs to.

Raises:

Type	Description
RuntimeError	Not integrated in a document yet.

parent: XmlFragment | XmlElement | XmlText | None property

The parent of this node, if any.

clear()

Removes the entire range of characters.

diff()

Returns:

Type	Description
list[tuple[Any, dict[str, Any] | None]]	A list of formatted chunks that the current text corresponds to. Each list item is a tuple containing the chunk's contents and formatting attributes. The contents is usually the text as a string, but may be other data for embedded objects.

format(start, stop, attrs)

Formats existing text with attributes.

Parameters:

Name	Type	Description	Default
start	int	The index at which to start applying the attributes (included).	required
stop	int	The index at which to stop applying the attributes (excluded).	required
attrs	dict[str, Any]	The attributes to apply.	required

insert(index, value, attrs=None)

Inserts text at a given index, with optional attributes.

Parameters:

Name	Type	Description	Default
index	int	The index at which to insert the text.	required
value	str	The text to insert.	required
attrs	Mapping[str, Any] | None	The optional attributes.	None

insert_embed(index, value, attrs=None)

Insert an embed at a given index in the text, with optional attributes.

Parameters:

Name	Type	Description	Default
index	int	The index at which to insert the embed.	required
value	Any	The embed to insert.	required
attrs	dict[str, Any] | None	The optional attributes.	None

observe_deep(callback)

Subscribes a callback for all events emitted by this and nested collaborative types.

Parameters:

Name	Type	Description	Default
callback	Callable[[list[BaseEvent]], None]	The callback to call with the list of events.	required

unobserve(subscription)

Unsubscribes to changes using the given subscription.

Parameters:

Name	Type	Description	Default
subscription	Subscription	The subscription to unregister.	required

YMessageType

Bases: IntEnum

A generic Y message type.

Attributes:

Name	Type	Description
SYNC	int	A message type used for synchronizing documents.
AWARENESS	int	A message type used for the awareness protocol.

YSyncMessageType

Bases: IntEnum

A message type used for synchronizing documents.

Attributes:

Name	Type	Description
SYNC_STEP1	int	A synchronization message type used to send a document state.
SYNC_STEP2	int	A synchronization message type used to reply to a SYNC_STEP1, consisting of all missing updates and all deletions.
SYNC_UPDATE	int	A synchronization message type used to send document updates.

create_awareness_message(data)

Creates an AWARENESS message.

Parameters:

Name	Type	Description	Default
data	bytes	The data to send in the message.	required

Returns:

Type	Description
bytes	The AWARENESS message.

create_sync_message(ydoc)

Creates a SYNC_STEP1 message that contains the state of a Doc.

Parameters:

Name	Type	Description	Default
ydoc	Doc	The Doc for which to create the message.	required

Returns:

Type	Description
bytes	A SYNC_STEP1 message.

create_update_message(data)

Creates a SYNC_UPDATE message that contains a document update.

Parameters:

Name	Type	Description	Default
data	bytes	The document update.	required

Returns:

Type	Description
bytes	A SYNC_UPDATE message.

handle_sync_message(message, ydoc)

Processes a synchronization message on a document.

Parameters:

Name	Type	Description	Default
message	bytes	A synchronization message.	required
ydoc	Doc	The Doc that this message targets.	required

Returns:

Type	Description
bytes | None	The SYNC_STEP2 reply message, if the message
bytes | None	was a SYNC_STEP1.

get_state(update)

Returns a state from an update.

Parameters:

Name	Type	Description	Default
update	bytes	The update from which to get the state.	required

Returns:

Type	Description
bytes	The state corresponding to the update.

get_update(update, state)

Returns an update consisting of all changes from a given update which have not been seen in the given state.

Parameters:

Name	Type	Description	Default
update	bytes	The update from which to get all missing changes in the given state.	required
state	bytes	The state from which to get missing changes that are in the given update.	required

Returns:

Type	Description
bytes	The changes from the given update not present in the given state.

merge_updates(*updates)

Returns an update consisting of a combination of all given updates.

Parameters:

Name	Type	Description	Default
updates	bytes	The updates to merge.	()

Returns:

Type	Description
bytes	The merged updates.

read_message(stream)

Reads a message from a byte stream.

Parameters:

Name	Type	Description	Default
stream	bytes	The byte stream from which to read the message.	required

Returns:

Type	Description
bytes	The message read from the byte stream.

write_message(stream)

Writes a stream in a message.

Parameters:

Name	Type	Description	Default
stream	bytes	The byte stream to write in a message.	required

Returns:

Type	Description
bytes	The message containing the stream.

write_var_uint(num)

Encodes a payload length.

Parameters:

Name	Type	Description	Default
num	int	The payload length to encode.	required

Returns:

Type	Description
bytes	The encoded payload length.