vcti-tree 1.0.0__tar.gz

vcti_tree-1.0.0/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2018-2026 Visual Collaboration Technologies Inc.
+All Rights Reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+distribution, or use of this software, via any medium, is strictly
+prohibited. Access is granted only to authorized VCollab developers
+and individuals explicitly authorized by Visual Collaboration
+Technologies Inc.

vcti_tree-1.0.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: vcti-tree
+Version: 1.0.0
+Summary: Tree protocols and generic algorithms for the vcti ecosystem. Zero-dependency abstractions; pluggable backings.
+Author: Visual Collaboration Technologies Inc.
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://github.com/vcollab/vcti-python-tree
+Project-URL: Repository, https://github.com/vcollab/vcti-python-tree
+Project-URL: Changelog, https://github.com/vcollab/vcti-python-tree/blob/main/CHANGELOG.md
+Keywords: tree,protocol,traversal,dfs,bfs,data-structure,generic-algorithms
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: mypy; extra == "typecheck"
+Dynamic: license-file
+
+# vcti-tree
+
+Tree protocols and generic algorithms for the vcti ecosystem.
+Zero-dependency abstractions; pluggable backings.
+
+## Overview
+
+`vcti-tree` defines what a tree is in the vcti ecosystem: three
+Protocols (`ReadOnlyTree`, `MutableTree`, `LockableTree`)
+parameterised in payload type `T` and handle type `H`, plus generic
+algorithms — DFS and BFS walks, ancestor/depth/path queries,
+locking guards — written against those Protocols. The Protocols
+specify *semantics* (what a tree must support); they do not
+prescribe storage. Any backing — numpy-array, pointer-based,
+dict-based — that satisfies the Protocols gets the algorithms for
+free. The package has no numpy or other heavy dependency; it is a
+pure-Python abstraction layer that downstream tree packages depend
+on.
+
+## Why this exists
+
+Tree code in the Python ecosystem typically bundles storage,
+mutation, and traversal into a single class — every new tree
+implementation re-implements its own walker, its own navigation
+helpers, its own delete semantics. This package brings across a
+pattern that's well-established in C++: a small abstract interface
+defining what a tree *is*, multiple concrete implementations
+choosing their own storage, and generic algorithms written once
+against the interface and reused across every backing. The result
+is that adding a new tree implementation (numpy-backed,
+pointer-backed, persistent, …) doesn't mean rewriting walkers and
+guards — it means satisfying three small Protocols and inheriting
+the entire algorithm library. See [docs/design.md](docs/design.md)
+for the full background and the design decisions.
+
+## Installation
+
+```bash
+pip install vcti-tree
+```
+
+### In `requirements.txt`
+
+```
+vcti-tree>=1.0.0
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-tree>=1.0.0",
+]
+```
+
+---
+
+## Quick Start
+
+The protocols and algorithms are the API; you bring (or import) a
+backing. `DictTree` is the bundled dict-backed reference
+implementation — enough to build a tree and run the generic algorithms
+against it:
+
+```python
+from vcti.tree import DictTree, dfs_preorder, ancestors, depth
+
+tree = DictTree[str]("root")            # every tree has a root from the start
+a = tree.create_child(tree.root_handle, "a")
+b = tree.create_child(tree.root_handle, "b")
+tree.create_child(a, "a1")
+
+# Generic walks/queries work against any tree that satisfies the protocols.
+print([tree.payload(h) for h in dfs_preorder(tree)])   # ['root', 'a', 'a1', 'b']
+print([tree.payload(h) for h in ancestors(tree, a)])   # ['root']
+print(depth(tree, a))                                  # 1
+```
+
+The protocols (`ReadOnlyTree`, `MutableTree`, `LockableTree`) and the
+rest of the algorithm set are importable from the same package root:
+
+```python
+from vcti.tree import ReadOnlyTree, MutableTree, LockableTree
+from vcti.tree import dfs_preorder, dfs_postorder, bfs
+from vcti.tree import ancestors, depth, path, descendants
+```
+
+---
+
+## Dependencies
+
+None. Standard library only.

vcti_tree-1.0.0/README.md

@@ -0,0 +1,92 @@
+# vcti-tree
+
+Tree protocols and generic algorithms for the vcti ecosystem.
+Zero-dependency abstractions; pluggable backings.
+
+## Overview
+
+`vcti-tree` defines what a tree is in the vcti ecosystem: three
+Protocols (`ReadOnlyTree`, `MutableTree`, `LockableTree`)
+parameterised in payload type `T` and handle type `H`, plus generic
+algorithms — DFS and BFS walks, ancestor/depth/path queries,
+locking guards — written against those Protocols. The Protocols
+specify *semantics* (what a tree must support); they do not
+prescribe storage. Any backing — numpy-array, pointer-based,
+dict-based — that satisfies the Protocols gets the algorithms for
+free. The package has no numpy or other heavy dependency; it is a
+pure-Python abstraction layer that downstream tree packages depend
+on.
+
+## Why this exists
+
+Tree code in the Python ecosystem typically bundles storage,
+mutation, and traversal into a single class — every new tree
+implementation re-implements its own walker, its own navigation
+helpers, its own delete semantics. This package brings across a
+pattern that's well-established in C++: a small abstract interface
+defining what a tree *is*, multiple concrete implementations
+choosing their own storage, and generic algorithms written once
+against the interface and reused across every backing. The result
+is that adding a new tree implementation (numpy-backed,
+pointer-backed, persistent, …) doesn't mean rewriting walkers and
+guards — it means satisfying three small Protocols and inheriting
+the entire algorithm library. See [docs/design.md](docs/design.md)
+for the full background and the design decisions.
+
+## Installation
+
+```bash
+pip install vcti-tree
+```
+
+### In `requirements.txt`
+
+```
+vcti-tree>=1.0.0
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-tree>=1.0.0",
+]
+```
+
+---
+
+## Quick Start
+
+The protocols and algorithms are the API; you bring (or import) a
+backing. `DictTree` is the bundled dict-backed reference
+implementation — enough to build a tree and run the generic algorithms
+against it:
+
+```python
+from vcti.tree import DictTree, dfs_preorder, ancestors, depth
+
+tree = DictTree[str]("root")            # every tree has a root from the start
+a = tree.create_child(tree.root_handle, "a")
+b = tree.create_child(tree.root_handle, "b")
+tree.create_child(a, "a1")
+
+# Generic walks/queries work against any tree that satisfies the protocols.
+print([tree.payload(h) for h in dfs_preorder(tree)])   # ['root', 'a', 'a1', 'b']
+print([tree.payload(h) for h in ancestors(tree, a)])   # ['root']
+print(depth(tree, a))                                  # 1
+```
+
+The protocols (`ReadOnlyTree`, `MutableTree`, `LockableTree`) and the
+rest of the algorithm set are importable from the same package root:
+
+```python
+from vcti.tree import ReadOnlyTree, MutableTree, LockableTree
+from vcti.tree import dfs_preorder, dfs_postorder, bfs
+from vcti.tree import ancestors, depth, path, descendants
+```
+
+---
+
+## Dependencies
+
+None. Standard library only.

vcti_tree-1.0.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vcti-tree"
+version = "1.0.0"
+description = "Tree protocols and generic algorithms for the vcti ecosystem. Zero-dependency abstractions; pluggable backings."
+readme = "README.md"
+authors = [
+    {name = "Visual Collaboration Technologies Inc."}
+]
+requires-python = ">=3.12,<3.15"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+keywords = ["tree", "protocol", "traversal", "dfs", "bfs", "data-structure", "generic-algorithms"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/vcollab/vcti-python-tree"
+Repository = "https://github.com/vcollab/vcti-python-tree"
+Changelog = "https://github.com/vcollab/vcti-python-tree/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["vcti.tree", "vcti.tree.*"]
+
+[tool.setuptools.package-data]
+"vcti.tree" = ["py.typed"]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov"]
+lint = ["ruff"]
+typecheck = ["mypy"]
+
+[tool.setuptools]
+zip-safe = true
+
+[tool.pytest.ini_options]
+addopts = "--cov=vcti.tree --cov-report=term-missing --cov-fail-under=95"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src"]
+namespace_packages = true
+explicit_package_bases = true
+mypy_path = ["src"]
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+exclude_also = [
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+    "@(abc\\.)?abstractmethod",
+    "\\.\\.\\.",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]

vcti_tree-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vcti_tree-1.0.0/src/vcti/tree/__init__.py

@@ -0,0 +1,41 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""vcti.tree — Tree protocols and generic algorithms for the vcti ecosystem."""
+
+from importlib.metadata import version
+
+from .dict_tree import DictTree, DictTreeHandle
+from .locking import (
+    collect_deletable_subtree,
+    ensure_payload_unlocked,
+    ensure_structure_unlocked,
+)
+from .navigation import ancestors, depth, descendants, path
+from .protocols import LockableTree, MutableTree, ReadOnlyTree
+from .walking import bfs, dfs_postorder, dfs_preorder
+
+__version__ = version("vcti-tree")
+
+__all__ = [
+    "__version__",
+    # Protocols
+    "ReadOnlyTree",
+    "MutableTree",
+    "LockableTree",
+    # Walking
+    "dfs_preorder",
+    "dfs_postorder",
+    "bfs",
+    # Navigation
+    "ancestors",
+    "depth",
+    "path",
+    "descendants",
+    # Locking guards
+    "collect_deletable_subtree",
+    "ensure_structure_unlocked",
+    "ensure_payload_unlocked",
+    # Reference implementation
+    "DictTree",
+    "DictTreeHandle",
+]

vcti_tree-1.0.0/src/vcti/tree/dict_tree.py

@@ -0,0 +1,240 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""DictTree — minimal dict-backed reference implementation of LockableTree.
+
+A simple in-memory tree backed by a Python dict of node records, used
+internally for testing the generic algorithms in
+:mod:`vcti.tree.walking`, :mod:`vcti.tree.navigation`, and
+:mod:`vcti.tree.locking` without pulling in numpy or other heavy
+dependencies. Also serves as a working example of how to implement
+:class:`~vcti.tree.protocols.LockableTree` from scratch.
+
+This is **not** the recommended production implementation — for
+numpy-backed storage at file-structure-tree scale, use
+``vcti-nptree``'s ``ArrayTree``.
+
+Handle representation
+---------------------
+
+Handles are ``DictTreeHandle(tree_id, key)`` named tuples:
+
+- ``tree_id`` is a process-global counter incremented on each
+  ``DictTree`` construction, so handles from different trees compare
+  unequal (the cross-tree inequality requirement of the protocol).
+- ``key`` is an integer slot key auto-generated inside the tree.
+
+The tuple wrapping is the minimum needed to satisfy cross-tree
+inequality on top of bare keys.
+"""
+
+from collections.abc import Hashable, Iterable, Iterator
+from dataclasses import dataclass, field
+from itertools import count
+from typing import NamedTuple
+
+from .locking import collect_deletable_subtree
+
+# Process-global counter; one tag per DictTree instance.
+_tree_id_counter = count(1)
+
+
+class DictTreeHandle(NamedTuple):
+    """Opaque handle to a node in a :class:`DictTree`."""
+
+    tree_id: int
+    key: int
+
+
+@dataclass
+class _NodeRecord[T]:
+    """Internal storage for one node."""
+
+    parent: int | None  # parent key; None for root
+    children: list[int] = field(default_factory=list)
+    payload: T | None = None
+    active: bool = True
+    structure_locked: bool = False
+    payload_locked: bool = False
+
+
+class DictTree[T]:
+    """Dict-backed reference implementation of
+    :class:`~vcti.tree.protocols.LockableTree`.
+
+    Satisfies ``LockableTree[T, DictTreeHandle]`` via the structural-
+    typing protocol. Soft-delete model (matches the ``ArrayTree``
+    semantics): :meth:`delete_subtree` marks nodes inactive but leaves
+    them in the parent's children list; ``children()`` filters them out.
+
+    Locks are flat bitsets propagated across the whole active subtree
+    on each ``lock_*`` / ``unlock_*`` call (no refcount).
+    """
+
+    def __init__(self, root_data: T | None = None) -> None:
+        self._tree_id: int = next(_tree_id_counter)
+        self._next_key: int = 0
+        self._records: dict[int, _NodeRecord[T]] = {}
+        self._active_count: int = 0
+        # Allocate root at key 0 with parent=None.
+        root_key = self._allocate(parent=None, data=root_data)
+        self._root_key: int = root_key
+
+    # ---- handle (un)wrapping ----
+
+    def _unwrap(self, handle: DictTreeHandle) -> int:
+        if handle.tree_id != self._tree_id:
+            raise LookupError(
+                f"Handle {handle} is from a different tree (this tree's id={self._tree_id})"
+            )
+        if handle.key not in self._records:
+            raise KeyError(f"Handle {handle} refers to a key that was never allocated")
+        return handle.key
+
+    def _wrap(self, key: int) -> DictTreeHandle:
+        return DictTreeHandle(self._tree_id, key)
+
+    def _require_active(self, handle: DictTreeHandle) -> tuple[int, "_NodeRecord[T]"]:
+        """Unwrap ``handle`` and return ``(key, record)`` for a live node.
+
+        Raises:
+            LookupError: handle is from a different tree.
+            KeyError: handle's key was never allocated.
+            ValueError: the node has been soft-deleted.
+        """
+        key = self._unwrap(handle)
+        rec = self._records[key]
+        if not rec.active:
+            raise ValueError(f"Node {handle} has been deleted")
+        return key, rec
+
+    # ---- internal allocation ----
+
+    def _allocate(self, parent: int | None, data: T | None) -> int:
+        key = self._next_key
+        self._next_key += 1
+        self._records[key] = _NodeRecord(parent=parent, payload=data)
+        self._active_count += 1
+        return key
+
+    # ---- ReadOnlyTree ----
+
+    @property
+    def root_handle(self) -> DictTreeHandle:
+        return self._wrap(self._root_key)
+
+    def payload(self, handle: DictTreeHandle) -> T | None:
+        _, rec = self._require_active(handle)
+        return rec.payload
+
+    def parent(self, handle: DictTreeHandle) -> DictTreeHandle | None:
+        _, rec = self._require_active(handle)
+        return None if rec.parent is None else self._wrap(rec.parent)
+
+    def children(self, handle: DictTreeHandle) -> Iterable[DictTreeHandle]:
+        _, rec = self._require_active(handle)
+        # Walk the full child list, skip inactive — do not terminate early.
+        return [
+            self._wrap(child_key) for child_key in rec.children if self._records[child_key].active
+        ]
+
+    def __contains__(self, handle: object) -> bool:
+        if not isinstance(handle, DictTreeHandle):
+            return False
+        if handle.tree_id != self._tree_id:
+            return False
+        rec = self._records.get(handle.key)
+        return rec is not None and rec.active
+
+    def __iter__(self) -> Iterator[DictTreeHandle]:
+        for key, rec in self._records.items():
+            if rec.active:
+                yield self._wrap(key)
+
+    def __len__(self) -> int:
+        return self._active_count
+
+    # ---- MutableTree ----
+
+    def set_payload(self, handle: DictTreeHandle, data: T | None) -> None:
+        _, rec = self._require_active(handle)
+        if rec.payload_locked:
+            raise RuntimeError(f"Node {handle} is payload-locked")
+        rec.payload = data
+
+    def create_child(self, parent: DictTreeHandle, data: T | None = None) -> DictTreeHandle:
+        parent_key, parent_rec = self._require_active(parent)
+        if parent_rec.structure_locked:
+            raise RuntimeError(f"Parent {parent} is structure-locked")
+        child_key = self._allocate(parent=parent_key, data=data)
+        parent_rec.children.append(child_key)
+        return self._wrap(child_key)
+
+    def delete_subtree(self, handle: DictTreeHandle) -> None:
+        _, rec = self._require_active(handle)
+        if rec.parent is None:
+            raise RuntimeError("Cannot delete the root")
+        # Fail-fast collect via the shared protocol-level helper (raises if
+        # any node in the subtree is structure-locked), then deactivate the
+        # whole set atomically — no partial deletion on a locked subtree.
+        to_delete = collect_deletable_subtree(self, handle)
+        for h in to_delete:
+            self._records[h.key].active = False
+        self._active_count -= len(to_delete)
+
+    # ---- LockableTree ----
+
+    def is_structure_locked(self, handle: DictTreeHandle) -> bool:
+        _, rec = self._require_active(handle)
+        return rec.structure_locked
+
+    def is_payload_locked(self, handle: DictTreeHandle) -> bool:
+        _, rec = self._require_active(handle)
+        return rec.payload_locked
+
+    def lock_structure(self, handle: DictTreeHandle) -> None:
+        self._apply_flag(handle, "structure_locked", True)
+
+    def unlock_structure(self, handle: DictTreeHandle) -> None:
+        self._apply_flag(handle, "structure_locked", False)
+
+    def lock_payload(self, handle: DictTreeHandle) -> None:
+        self._apply_flag(handle, "payload_locked", True)
+
+    def unlock_payload(self, handle: DictTreeHandle) -> None:
+        self._apply_flag(handle, "payload_locked", False)
+
+    def _apply_flag(self, handle: DictTreeHandle, attr: str, value: bool) -> None:
+        """Set ``attr=value`` on ``handle`` and all active descendants.
+
+        Raises if ``handle`` itself is not a live node (so lock/unlock on a
+        deleted handle fails loudly, consistent with the rest of the surface
+        rather than silently no-op'ing). Inactive *descendants* are skipped:
+        propagation covers the active subtree only.
+        """
+        root_key, _ = self._require_active(handle)
+        # Walk the subtree skipping inactive nodes; full child-chain walk.
+        stack: list[int] = [root_key]
+        while stack:
+            k = stack.pop()
+            rec = self._records[k]
+            if not rec.active:
+                continue
+            setattr(rec, attr, value)
+            for child_key in reversed(rec.children):
+                stack.append(child_key)
+
+
+# Static structural conformance check (mypy will see this).
+def _check_protocol_conformance() -> None:  # pragma: no cover
+    from .protocols import LockableTree, MutableTree, ReadOnlyTree
+
+    tree: DictTree[str] = DictTree("root")
+    _ro: ReadOnlyTree[str, DictTreeHandle] = tree
+    _mu: MutableTree[str, DictTreeHandle] = tree
+    _lo: LockableTree[str, DictTreeHandle] = tree
+    _ = _ro, _mu, _lo
+
+
+def _is_hashable_handle() -> None:  # pragma: no cover
+    # Sanity: DictTreeHandle must satisfy H: Hashable bound.
+    _: Hashable = DictTreeHandle(1, 0)

vcti_tree-1.0.0/src/vcti/tree/locking.py

@@ -0,0 +1,78 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Locking guards over any :class:`LockableTree`.
+
+Two complementary helpers:
+
+- :func:`collect_deletable_subtree` is the fused common-case for
+  ``delete_subtree`` implementations — single-pass walk + structure-lock
+  check, fail-fast on the first locked node.
+- :func:`ensure_structure_unlocked` and :func:`ensure_payload_unlocked`
+  are predicate-only forms for arbitrary handle iterables (e.g.,
+  user-supplied selections) that don't need subtree walking.
+
+All three operate against the :class:`LockableTree` protocol — never
+against any concrete implementation.
+"""
+
+from collections.abc import Hashable, Iterable
+
+from .protocols import LockableTree
+from .walking import dfs_preorder
+
+
+def collect_deletable_subtree[T, H: Hashable](tree: LockableTree[T, H], root_handle: H) -> list[H]:
+    """Walk the subtree at ``root_handle`` DFS pre-order and verify
+    no node is structure-locked.
+
+    Returns the list of handles in DFS pre-order; callers can then
+    deactivate them atomically without rolling back.
+
+    Intentionally fused (walks + validates in a single pass) rather
+    than composing :func:`descendants` + :func:`ensure_structure_unlocked`,
+    so that an early-locked node fails fast without materialising the
+    rest of the subtree.
+
+    Raises:
+        RuntimeError: If any node in the subtree is structure-locked.
+    """
+    nodes: list[H] = []
+    for h in dfs_preorder(tree, root_handle):
+        if tree.is_structure_locked(h):
+            raise RuntimeError(
+                f"Cannot delete subtree at {root_handle}: node {h} is structure-locked"
+            )
+        nodes.append(h)
+    return nodes
+
+
+def ensure_structure_unlocked[T, H: Hashable](
+    tree: LockableTree[T, H], handles: Iterable[H]
+) -> None:
+    """Raise on the first structure-locked handle in ``handles``.
+
+    Use this when the caller already has a handle list (e.g., a
+    user-supplied selection or a result from a separate walk) and
+    doesn't need subtree collection. For the subtree-delete common
+    case, prefer :func:`collect_deletable_subtree` which does both
+    in a single pass.
+
+    Raises:
+        RuntimeError: On the first structure-locked handle.
+    """
+    for h in handles:
+        if tree.is_structure_locked(h):
+            raise RuntimeError(f"Node {h} is structure-locked")
+
+
+def ensure_payload_unlocked[T, H: Hashable](
+    tree: LockableTree[T, H], handles: Iterable[H]
+) -> None:
+    """Raise on the first payload-locked handle in ``handles``.
+
+    Raises:
+        RuntimeError: On the first payload-locked handle.
+    """
+    for h in handles:
+        if tree.is_payload_locked(h):
+            raise RuntimeError(f"Node {h} is payload-locked")