pycrdt 0.9.5__cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl → 0.12.45__cp311-cp311-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl

pycrdt/__init__.py

@@ -1,20 +1,49 @@
+from pkgutil import extend_path
+
+__path__ = extend_path(__path__, __name__)
+
 from ._array import Array as Array
 from ._array import ArrayEvent as ArrayEvent
+from ._array import TypedArray as TypedArray
+from ._awareness import Awareness as Awareness
+from ._awareness import is_awareness_disconnect_message as is_awareness_disconnect_message
 from ._doc import Doc as Doc
+from ._doc import TypedDoc as TypedDoc
 from ._map import Map as Map
 from ._map import MapEvent as MapEvent
+from ._map import TypedMap as TypedMap
+from ._provider import Channel as Channel
+from ._provider import Provider as Provider
+from ._pycrdt import DeleteSet as DeleteSet
+from ._pycrdt import StackItem as StackItem
+from ._pycrdt import SubdocsEvent as SubdocsEvent
 from ._pycrdt import Subscription as Subscription
 from ._pycrdt import TransactionEvent as TransactionEvent
+from ._snapshot import Snapshot as Snapshot
+from ._sticky_index import Assoc as Assoc
+from ._sticky_index import StickyIndex as StickyIndex
 from ._sync import Decoder as Decoder
+from ._sync import Encoder as Encoder
 from ._sync import YMessageType as YMessageType
 from ._sync import YSyncMessageType as YSyncMessageType
+from ._sync import create_awareness_message as create_awareness_message
 from ._sync import create_sync_message as create_sync_message
 from ._sync import create_update_message as create_update_message
 from ._sync import handle_sync_message as handle_sync_message
 from ._sync import read_message as read_message
+from ._sync import write_message as write_message
 from ._sync import write_var_uint as write_var_uint
 from ._text import Text as Text
 from ._text import TextEvent as TextEvent
+from ._transaction import NewTransaction as NewTransaction
 from ._transaction import ReadTransaction as ReadTransaction
 from ._transaction import Transaction as Transaction
 from ._undo import UndoManager as UndoManager
+from ._update import get_state as get_state
+from ._update import get_update as get_update
+from ._update import merge_updates as merge_updates
+from ._version import __version__ as __version__
+from ._xml import XmlElement as XmlElement
+from ._xml import XmlEvent as XmlEvent
+from ._xml import XmlFragment as XmlFragment
+from ._xml import XmlText as XmlText

pycrdt/_array.py

@@ -1,40 +1,57 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Callable, Generic, TypeVar, cast, overload
 
-from ._base import BaseDoc, BaseEvent, BaseType, base_types, event_types
+from ._base import BaseDoc, BaseEvent, BaseType, Sequence, Typed, base_types, event_types
 from ._pycrdt import Array as _Array
 from ._pycrdt import ArrayEvent as _ArrayEvent
+from ._pycrdt import Subscription
 
-if TYPE_CHECKING:  # pragma: no cover
+if TYPE_CHECKING:
     from ._doc import Doc
 
+T = TypeVar("T")
 
-class Array(BaseType):
-    _prelim: list | None
+
+class Array(Sequence, Generic[T]):
+    """
+    A collection used to store data in an indexed sequence structure, similar to a Python `list`.
+    """
+
+    _prelim: list[T] | None
     _integrated: _Array | None
 
     def __init__(
         self,
-        init: list | None = None,
+        init: list[T] | None = None,
         *,
         _doc: Doc | None = None,
         _integrated: _Array | None = None,
     ) -> None:
+        """
+        Creates an array with an optional initial value:
+        ```py
+        array0 = Array()
+        array1 = Array(["foo", 3, array0])
+        ```
+
+        Args:
+            init: The list from which to initialize the array.
+        """
         super().__init__(
             init=init,
             _doc=_doc,
             _integrated=_integrated,
         )
 
-    def _init(self, value: list[Any] | None) -> None:
+    def _init(self, value: list[T] | None) -> None:
         if value is None:
             return
         with self.doc.transaction():
             for i, v in enumerate(value):
                 self._set(i, v)
 
-    def _set(self, index: int, value: Any) -> None:
+    def _set(self, index: int, value: T) -> None:
         with self.doc.transaction() as txn:
             self._forbid_read_transaction(txn)
             if isinstance(value, BaseDoc):
@@ -49,27 +66,70 @@ class Array(BaseType):
                 self.integrated.insert(txn._txn, index, value)
 
     def _get_or_insert(self, name: str, doc: Doc) -> _Array:
-        return doc._doc.get_or_insert_array(name)
+        assert doc._txn is not None
+        assert doc._txn._txn is not None
+        return doc._doc.get_or_insert_array(doc._txn._txn, name)
 
     def __len__(self) -> int:
+        """
+        ```py
+        Doc()["array"] = array = Array([2, 3, 0])
+        assert len(array) == 3
+        ```
+
+        Returns:
+            The length of the array.
+        """
         with self.doc.transaction() as txn:
             return self.integrated.len(txn._txn)
 
-    def append(self, value: Any) -> None:
+    def append(self, value: T) -> None:
+        """
+        Appends an item to the array.
+
+        Args:
+            value: The item to append to the array.
+        """
         with self.doc.transaction():
             self += [value]
 
-    def extend(self, value: list[Any]) -> None:
+    def extend(self, value: list[T]) -> None:
+        """
+        Extends the array with a list of items.
+
+        Args:
+            value: The items that will extend the array.
+        """
         with self.doc.transaction():
             self += value
 
     def clear(self) -> None:
+        """
+        Removes all items from the array.
+        """
         del self[:]
 
-    def insert(self, index, object) -> None:
+    def insert(self, index: int, object: T) -> None:
+        """
+        Inserts an item at a given index in the array.
+
+        Args:
+            index: The index where to insert the item.
+            object: The item to insert in the array.
+        """
         self[index:index] = [object]
 
-    def pop(self, index: int = -1) -> Any:
+    def pop(self, index: int = -1) -> T:
+        """
+        Removes the item at the given index from the array, and returns it.
+        If no index is passed, removes and returns the last item.
+
+        Args:
+            index: The optional index of the item to pop.
+
+        Returns:
+            The item at the given index, or the last item.
+        """
         with self.doc.transaction():
             index = self._check_index(index)
             res = self[index]
@@ -79,24 +139,80 @@ class Array(BaseType):
             return res
 
     def move(self, source_index: int, destination_index: int) -> None:
+        """
+        Moves an item in the array from a source index to a destination index.
+
+        Args:
+            source_index: The index of the item to move.
+            destination_index: The index where the item will be inserted.
+        """
         with self.doc.transaction() as txn:
             self._forbid_read_transaction(txn)
             source_index = self._check_index(source_index)
             destination_index = self._check_index(destination_index)
             self.integrated.move_to(txn._txn, source_index, destination_index)
 
-    def __add__(self, value: list[Any]) -> Array:
+    def __add__(self, value: list[T]) -> Array[T]:
+        """
+        Extends the array with a list of items:
+        ```py
+        Doc()["array"] = array = Array(["foo"])
+        array += ["bar", "baz"]
+        assert array.to_py() == ["foo", "bar", "baz"]
+        ```
+
+        Args:
+            value: The items that will extend the array.
+
+        Returns:
+            The extended array.
+        """
         with self.doc.transaction():
             length = len(self)
             self[length:length] = value
             return self
 
-    def __radd__(self, value: list[Any]) -> Array:
+    def __radd__(self, value: list[T]) -> Array[T]:
+        """
+        Prepends a list of items to the array:
+        ```py
+        Doc()["array"] = array = Array(["bar", "baz"])
+        array = ["foo"] + array
+        assert array.to_py() == ["foo", "bar", "baz"]
+        ```
+
+        Args:
+            value: The list of items to prepend.
+
+        Returns:
+            The prepended array.
+        """
         with self.doc.transaction():
             self[0:0] = value
             return self
 
-    def __setitem__(self, key: int | slice, value: Any | list[Any]) -> None:
+    @overload
+    def __setitem__(self, key: int, value: T) -> None: ...
+
+    @overload
+    def __setitem__(self, key: slice, value: list[T]) -> None: ...
+
+    def __setitem__(self, key, value):
+        """
+        Replaces the item at the given index with a new item:
+        ```py
+        Doc()["array"] = array = Array(["foo", "bar"])
+        array[1] = "baz"
+        assert array.to_py() == ["foo", "baz"]
+        ```
+
+        Args:
+            key: The index of the item to replace.
+            value: The new item to set.
+
+        Raises:
+            RuntimeError: Index must be of type integer.
+        """
         with self.doc.transaction():
             if isinstance(key, int):
                 key = self._check_index(key)
@@ -125,6 +241,20 @@ class Array(BaseType):
         return idx
 
     def __delitem__(self, key: int | slice) -> None:
+        """
+        Removes the item at the given index from the array:
+        ```py
+        Doc()["array"] = array = Array(["foo", "bar", "baz"])
+        del array[2]
+        assert array.to_py() == ["foo", "bar"]
+        ```
+
+        Args:
+            key: The index of the item to remove.
+
+        Raises:
+            RuntimeError: Array indices must be integers or slices.
+        """
         with self.doc.transaction() as txn:
             self._forbid_read_transaction(txn)
             if isinstance(key, int):
@@ -148,10 +278,26 @@ class Array(BaseType):
                 self.integrated.remove_range(txn._txn, i, n)
             else:
                 raise TypeError(
-                    f"array indices must be integers or slices, not {type(key).__name__}"
+                    f"Array indices must be integers or slices, not {type(key).__name__}"
                 )
 
-    def __getitem__(self, key: int) -> BaseType:
+    @overload
+    def __getitem__(self, key: int) -> T: ...
+
+    @overload
+    def __getitem__(self, key: slice) -> list[T]: ...
+
+    def __getitem__(self, key):
+        """
+        Gets the item at the given index:
+        ```py
+        Doc()["array"] = array = Array(["foo", "bar", "baz"])
+        assert array[1] == "bar"
+        ```
+
+        Returns:
+            The item at the given index.
+        """
         with self.doc.transaction() as txn:
             if isinstance(key, int):
                 key = self._check_index(key)
@@ -162,30 +308,87 @@ class Array(BaseType):
                 step = 1 if key.step is None else key.step
                 return [self[i] for i in range(i0, i1, step)]
 
-    def __iter__(self):
+    def __iter__(self) -> ArrayIterator:
+        """
+        ```py
+        Doc()["array"] = array = Array(["foo", "foo"])
+        for value in array:
+            assert value == "foo"
+        ```
+        Returns:
+            An iterable over the items of the array.
+        """
         return ArrayIterator(self)
 
-    def __contains__(self, item: Any) -> bool:
-        return item in list(self)
+    def __contains__(self, item: T) -> bool:
+        """
+        Checks if the given item is in the array:
+        ```py
+        Doc()["array"] = array = Array(["foo", "bar"])
+        assert "baz" not in array
+        ```
+
+        Args:
+            item: The item to look for in the array.
+
+        Returns:
+            True if the item was found.
+        """
+        return item in [value for value in self]
 
     def __str__(self) -> str:
+        """
+        ```py
+        Doc()["array"] = array = Array([2, 3, 0])
+        assert str(array) == "[2,3,0]"
+        ```
+
+        Returns:
+            The string representation of the array.
+        """
         with self.doc.transaction() as txn:
             return self.integrated.to_json(txn._txn)
 
-    def to_py(self) -> list | None:
+    def to_py(self) -> list[T] | None:
+        """
+        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:
+            The array recursively converted to Python objects, or `None`.
+        """
         if self._integrated is None:
             py = self._prelim
             if py is None:
                 return None
         else:
-            py = list(self)
+            py = [value for value in self]
         for idx, val in enumerate(py):
             if isinstance(val, BaseType):
                 py[idx] = val.to_py()
         return py
 
+    def observe(self, callback: Callable[[ArrayEvent], None]) -> Subscription:
+        """
+        Subscribes a callback to be called with the array event.
+
+        Args:
+            callback: The callback to call with the [ArrayEvent][pycrdt.ArrayEvent].
+        """
+        return super().observe(cast(Callable[[BaseEvent], None], callback))
+
 
 class ArrayEvent(BaseEvent):
+    """
+    An array change event.
+
+    Attributes:
+        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.
+    """
+
     __slots__ = "target", "delta", "path"
 
 
@@ -195,7 +398,10 @@ class ArrayIterator:
         self.length = len(array)
         self.idx = 0
 
-    def __next__(self):
+    def __iter__(self) -> ArrayIterator:
+        return self  # pragma: nocover
+
+    def __next__(self) -> Any:
         if self.idx == self.length:
             raise StopIteration
 
@@ -204,5 +410,76 @@ class ArrayIterator:
         return res
 
 
+class TypedArray(Typed, Generic[T]):
+    """
+    A container for an [Array][pycrdt.Array.__init__] where values have types that can be
+    other typed containers, e.g. a [TypedMap][pycrdt.TypedMap]. The subclass of `TypedArray[T]`
+    must have a special `type: T` annotation where `T` is the same type.
+    The underlying `Array` can be accessed with the special `_` attribute.
+
+    ```py
+    from pycrdt import Array, TypedArray, TypedDoc, TypedMap
+
+    class MyMap(TypedMap):
+        name: str
+        toggle: bool
+        nested: Array[bool]
+
+    class MyArray(TypedArray[MyMap]):
+        type: MyMap
+
+    class MyDoc(TypedDoc):
+        array0: MyArray
+
+    doc = MyDoc()
+
+    map0 = MyMap()
+    doc.array0.append(map0)
+    map0.name = "foo"
+    map0.toggle = True
+    map0.nested = Array([True, False])
+
+    print(doc.array0._.to_py())
+    # [{'name': 'foo', 'toggle': True, 'nested': [True, False]}]
+    print(doc.array0[0].name)
+    # foo
+    print(doc.array0[0].toggle)
+    # True
+    print(doc.array0[0].nested.to_py())
+    # [True, False]
+    ```
+    """
+
+    type: T
+    _: Array
+
+    def __init__(self, array: TypedArray | Array | None = None) -> None:
+        super().__init__()
+        if array is None:
+            array = Array()
+        elif isinstance(array, TypedArray):
+            array = array._
+        self._ = array
+        self.__dict__["type"] = self.__dict__["annotations"]["type"]
+
+    def __getitem__(self, key: int) -> T:
+        return self.__dict__["type"](self._[key])
+
+    def __setitem__(self, key: int, value: T) -> None:
+        item = value._ if isinstance(value, Typed) else value
+        self._[key] = item
+
+    def append(self, value: T) -> None:
+        item = value._ if isinstance(value, Typed) else value
+        self._.append(item)
+
+    def extend(self, value: list[T]) -> None:
+        items = [item._ if isinstance(item, Typed) else item for item in value]
+        self._.extend(items)
+
+    def __len__(self) -> int:
+        return len(self._)
+
+
 base_types[_Array] = Array
 event_types[_ArrayEvent] = ArrayEvent