msaas-folder-hierarchy 0.1.0__tar.gz

msaas_folder_hierarchy-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+node_modules/
+dist/
+.next/
+.turbo/
+*.pyc
+__pycache__/
+.venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env
+.env.*
+!.env.example
+!.env.*.example
+!.env.*.template
+.DS_Store
+coverage/
+
+# Runtime artifacts
+logs_llm/
+vectors.db
+vectors.db-shm
+vectors.db-wal

msaas_folder_hierarchy-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: msaas-folder-hierarchy
+Version: 0.1.0
+Summary: Materialized path tree structure for hierarchical folders with move, copy, and depth tracking
+Requires-Python: >=3.12
+Requires-Dist: msaas-api-core
+Requires-Dist: msaas-errors
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

msaas_folder_hierarchy-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "msaas-folder-hierarchy"
+version = "0.1.0"
+description = "Materialized path tree structure for hierarchical folders with move, copy, and depth tracking"
+requires-python = ">=3.12"
+dependencies = [
+    "msaas-api-core",
+    "msaas-errors",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/folder_hierarchy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "TCH"]
+
+[tool.uv.sources]
+msaas-api-core = { workspace = true }
+msaas-errors = { workspace = true }

msaas_folder_hierarchy-0.1.0/src/folder_hierarchy/__init__.py

@@ -0,0 +1,19 @@
+"""Willian Folder Hierarchy -- Materialized path tree structure management."""
+
+from folder_hierarchy.models import (
+    FolderCreate,
+    FolderMove,
+    FolderNode,
+    FolderTree,
+    FolderUpdate,
+)
+from folder_hierarchy.service import FolderHierarchyService
+
+__all__ = [
+    "FolderCreate",
+    "FolderHierarchyService",
+    "FolderMove",
+    "FolderNode",
+    "FolderTree",
+    "FolderUpdate",
+]

msaas_folder_hierarchy-0.1.0/src/folder_hierarchy/models.py

@@ -0,0 +1,59 @@
+"""Folder hierarchy data models."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+
+class FolderNode(BaseModel):
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    name: str
+    path: str = "/"
+    parent_id: str | None = None
+    depth: int = 0
+    tenant_id: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime = Field(default_factory=_utcnow)
+    updated_at: datetime = Field(default_factory=_utcnow)
+    children: list[FolderNode] = Field(default_factory=list)
+    item_count: int = 0
+
+    @property
+    def is_root(self) -> bool:
+        return self.parent_id is None
+
+    @property
+    def path_parts(self) -> list[str]:
+        return [p for p in self.path.split("/") if p]
+
+
+class FolderCreate(BaseModel):
+    name: str = Field(min_length=1, max_length=255)
+    parent_id: str | None = None
+    tenant_id: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class FolderUpdate(BaseModel):
+    name: str | None = Field(default=None, min_length=1, max_length=255)
+    metadata: dict[str, Any] | None = None
+
+
+class FolderMove(BaseModel):
+    target_parent_id: str | None = None
+
+
+class FolderTree(BaseModel):
+    roots: list[FolderNode] = Field(default_factory=list)
+    total_count: int = 0
+    max_depth: int = 0

msaas_folder_hierarchy-0.1.0/src/folder_hierarchy/service.py

@@ -0,0 +1,216 @@
+"""Folder hierarchy service with in-memory storage."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from folder_hierarchy.models import (
+    FolderCreate,
+    FolderMove,
+    FolderNode,
+    FolderTree,
+    FolderUpdate,
+)
+
+
+class FolderHierarchyService:
+    """Manages hierarchical folder structures using materialized paths."""
+
+    def __init__(self) -> None:
+        self._folders: dict[str, FolderNode] = {}
+
+    def create(self, params: FolderCreate) -> FolderNode:
+        if params.parent_id:
+            parent = self._get_folder(params.parent_id)
+            self._check_duplicate(params.name, params.parent_id, params.tenant_id)
+            path = f"{parent.path}{parent.name}/"
+            depth = parent.depth + 1
+        else:
+            self._check_duplicate(params.name, None, params.tenant_id)
+            path = "/"
+            depth = 0
+
+        folder = FolderNode(
+            name=params.name,
+            path=path,
+            parent_id=params.parent_id,
+            depth=depth,
+            tenant_id=params.tenant_id,
+            metadata=params.metadata,
+        )
+        self._folders[folder.id] = folder
+        return folder
+
+    def get(self, folder_id: str) -> FolderNode:
+        return self._get_folder(folder_id)
+
+    def update(self, folder_id: str, params: FolderUpdate) -> FolderNode:
+        folder = self._get_folder(folder_id)
+        if params.name is not None:
+            self._check_duplicate(
+                params.name, folder.parent_id, folder.tenant_id, exclude_id=folder_id
+            )
+            old_path_prefix = f"{folder.path}{folder.name}/"
+            folder.name = params.name
+            new_path_prefix = f"{folder.path}{folder.name}/"
+            self._update_children_paths(old_path_prefix, new_path_prefix)
+        if params.metadata is not None:
+            folder.metadata = params.metadata
+        folder.updated_at = datetime.now(UTC)
+        return folder
+
+    def delete(self, folder_id: str, recursive: bool = False) -> list[str]:
+        folder = self._get_folder(folder_id)
+        children = self._get_children(folder_id)
+
+        if children and not recursive:
+            from errors import BusinessLogicError
+
+            raise BusinessLogicError(
+                message=f"Folder '{folder.name}' has {len(children)} children. "
+                "Use recursive=True to delete."
+            )
+
+        deleted_ids: list[str] = []
+        if recursive:
+            descendants = self._get_descendants(folder_id)
+            for d in reversed(descendants):
+                del self._folders[d.id]
+                deleted_ids.append(d.id)
+
+        del self._folders[folder_id]
+        deleted_ids.append(folder_id)
+        return deleted_ids
+
+    def move(self, folder_id: str, params: FolderMove) -> FolderNode:
+        folder = self._get_folder(folder_id)
+
+        if params.target_parent_id:
+            target = self._get_folder(params.target_parent_id)
+            if self._is_descendant(params.target_parent_id, folder_id):
+                from errors import BusinessLogicError
+
+                raise BusinessLogicError(message="Cannot move folder into its own descendant")
+            self._check_duplicate(
+                folder.name, params.target_parent_id, folder.tenant_id, exclude_id=folder_id
+            )
+            new_path = f"{target.path}{target.name}/"
+            new_depth = target.depth + 1
+        else:
+            self._check_duplicate(folder.name, None, folder.tenant_id, exclude_id=folder_id)
+            new_path = "/"
+            new_depth = 0
+
+        old_path_prefix = f"{folder.path}{folder.name}/"
+        folder.parent_id = params.target_parent_id
+        folder.path = new_path
+        folder.depth = new_depth
+        folder.updated_at = datetime.now(UTC)
+
+        new_path_prefix = f"{new_path}{folder.name}/"
+        self._update_children_paths(old_path_prefix, new_path_prefix)
+        self._update_children_depth(folder_id, new_depth + 1)
+
+        return folder
+
+    def get_tree(self, tenant_id: str | None = None) -> FolderTree:
+        roots = [
+            f
+            for f in self._folders.values()
+            if f.parent_id is None and (tenant_id is None or f.tenant_id == tenant_id)
+        ]
+        for root in roots:
+            self._build_tree(root)
+        max_depth = max((f.depth for f in self._folders.values()), default=0)
+        return FolderTree(
+            roots=roots,
+            total_count=len(self._folders),
+            max_depth=max_depth,
+        )
+
+    def get_children(self, folder_id: str) -> list[FolderNode]:
+        self._get_folder(folder_id)
+        return self._get_children(folder_id)
+
+    def get_ancestors(self, folder_id: str) -> list[FolderNode]:
+        folder = self._get_folder(folder_id)
+        ancestors: list[FolderNode] = []
+        current = folder
+        while current.parent_id:
+            parent = self._folders.get(current.parent_id)
+            if parent is None:
+                break
+            ancestors.append(parent)
+            current = parent
+        ancestors.reverse()
+        return ancestors
+
+    def get_breadcrumb(self, folder_id: str) -> list[dict[str, str]]:
+        ancestors = self.get_ancestors(folder_id)
+        folder = self._get_folder(folder_id)
+        return [{"id": a.id, "name": a.name} for a in ancestors] + [
+            {"id": folder.id, "name": folder.name}
+        ]
+
+    def _get_folder(self, folder_id: str) -> FolderNode:
+        folder = self._folders.get(folder_id)
+        if folder is None:
+            from errors import NotFoundError
+
+            raise NotFoundError(message=f"Folder {folder_id} not found")
+        return folder
+
+    def _get_children(self, parent_id: str) -> list[FolderNode]:
+        return [f for f in self._folders.values() if f.parent_id == parent_id]
+
+    def _get_descendants(self, folder_id: str) -> list[FolderNode]:
+        descendants: list[FolderNode] = []
+        children = self._get_children(folder_id)
+        for child in children:
+            descendants.append(child)
+            descendants.extend(self._get_descendants(child.id))
+        return descendants
+
+    def _is_descendant(self, folder_id: str, ancestor_id: str) -> bool:
+        current = self._folders.get(folder_id)
+        while current:
+            if current.id == ancestor_id:
+                return True
+            if current.parent_id is None:
+                break
+            current = self._folders.get(current.parent_id)
+        return False
+
+    def _check_duplicate(
+        self,
+        name: str,
+        parent_id: str | None,
+        tenant_id: str | None,
+        exclude_id: str | None = None,
+    ) -> None:
+        for f in self._folders.values():
+            if (
+                f.name == name
+                and f.parent_id == parent_id
+                and f.tenant_id == tenant_id
+                and f.id != exclude_id
+            ):
+                from errors import ConflictError
+
+                raise ConflictError(message=f"Folder '{name}' already exists in this location")
+
+    def _build_tree(self, node: FolderNode) -> None:
+        node.children = self._get_children(node.id)
+        for child in node.children:
+            self._build_tree(child)
+
+    def _update_children_paths(self, old_prefix: str, new_prefix: str) -> None:
+        for f in self._folders.values():
+            if f.path.startswith(old_prefix):
+                f.path = new_prefix + f.path[len(old_prefix) :]
+
+    def _update_children_depth(self, parent_id: str, depth: int) -> None:
+        children = self._get_children(parent_id)
+        for child in children:
+            child.depth = depth
+            self._update_children_depth(child.id, depth + 1)

msaas_folder_hierarchy-0.1.0/tests/test_service.py

@@ -0,0 +1,113 @@
+"""Tests for folder hierarchy service."""
+
+from __future__ import annotations
+
+import pytest
+
+from folder_hierarchy.models import FolderCreate, FolderMove, FolderUpdate
+from folder_hierarchy.service import FolderHierarchyService
+
+
+class TestFolderHierarchyService:
+    def setup_method(self) -> None:
+        self.service = FolderHierarchyService()
+
+    def test_create_root_folder(self) -> None:
+        folder = self.service.create(FolderCreate(name="Documents"))
+        assert folder.name == "Documents"
+        assert folder.path == "/"
+        assert folder.depth == 0
+        assert folder.is_root is True
+
+    def test_create_nested_folder(self) -> None:
+        root = self.service.create(FolderCreate(name="Documents"))
+        child = self.service.create(FolderCreate(name="Reports", parent_id=root.id))
+        assert child.path == "/Documents/"
+        assert child.depth == 1
+        assert child.parent_id == root.id
+
+    def test_create_deeply_nested(self) -> None:
+        root = self.service.create(FolderCreate(name="A"))
+        b = self.service.create(FolderCreate(name="B", parent_id=root.id))
+        c = self.service.create(FolderCreate(name="C", parent_id=b.id))
+        assert c.path == "/A/B/"
+        assert c.depth == 2
+
+    def test_duplicate_name_same_parent_fails(self) -> None:
+        self.service.create(FolderCreate(name="Docs"))
+        with pytest.raises(Exception, match="already exists"):
+            self.service.create(FolderCreate(name="Docs"))
+
+    def test_same_name_different_parent_ok(self) -> None:
+        root1 = self.service.create(FolderCreate(name="A"))
+        root2 = self.service.create(FolderCreate(name="B"))
+        f1 = self.service.create(FolderCreate(name="Docs", parent_id=root1.id))
+        f2 = self.service.create(FolderCreate(name="Docs", parent_id=root2.id))
+        assert f1.id != f2.id
+
+    def test_update_name(self) -> None:
+        folder = self.service.create(FolderCreate(name="Old"))
+        updated = self.service.update(folder.id, FolderUpdate(name="New"))
+        assert updated.name == "New"
+
+    def test_delete_empty_folder(self) -> None:
+        folder = self.service.create(FolderCreate(name="Temp"))
+        deleted = self.service.delete(folder.id)
+        assert folder.id in deleted
+
+    def test_delete_with_children_fails(self) -> None:
+        root = self.service.create(FolderCreate(name="Root"))
+        self.service.create(FolderCreate(name="Child", parent_id=root.id))
+        with pytest.raises(Exception, match="children"):
+            self.service.delete(root.id)
+
+    def test_delete_recursive(self) -> None:
+        root = self.service.create(FolderCreate(name="Root"))
+        child = self.service.create(FolderCreate(name="Child", parent_id=root.id))
+        deleted = self.service.delete(root.id, recursive=True)
+        assert len(deleted) == 2
+
+    def test_move_folder(self) -> None:
+        a = self.service.create(FolderCreate(name="A"))
+        b = self.service.create(FolderCreate(name="B"))
+        child = self.service.create(FolderCreate(name="X", parent_id=a.id))
+        moved = self.service.move(child.id, FolderMove(target_parent_id=b.id))
+        assert moved.parent_id == b.id
+        assert moved.path == "/B/"
+
+    def test_move_into_descendant_fails(self) -> None:
+        root = self.service.create(FolderCreate(name="Root"))
+        child = self.service.create(FolderCreate(name="Child", parent_id=root.id))
+        with pytest.raises(Exception, match="descendant"):
+            self.service.move(root.id, FolderMove(target_parent_id=child.id))
+
+    def test_get_tree(self) -> None:
+        root = self.service.create(FolderCreate(name="Root"))
+        self.service.create(FolderCreate(name="Child", parent_id=root.id))
+        tree = self.service.get_tree()
+        assert tree.total_count == 2
+        assert len(tree.roots) == 1
+        assert len(tree.roots[0].children) == 1
+
+    def test_get_ancestors(self) -> None:
+        a = self.service.create(FolderCreate(name="A"))
+        b = self.service.create(FolderCreate(name="B", parent_id=a.id))
+        c = self.service.create(FolderCreate(name="C", parent_id=b.id))
+        ancestors = self.service.get_ancestors(c.id)
+        assert len(ancestors) == 2
+        assert ancestors[0].name == "A"
+        assert ancestors[1].name == "B"
+
+    def test_get_breadcrumb(self) -> None:
+        a = self.service.create(FolderCreate(name="A"))
+        b = self.service.create(FolderCreate(name="B", parent_id=a.id))
+        crumbs = self.service.get_breadcrumb(b.id)
+        assert len(crumbs) == 2
+        assert crumbs[0]["name"] == "A"
+        assert crumbs[1]["name"] == "B"
+
+    def test_tenant_isolation(self) -> None:
+        self.service.create(FolderCreate(name="X", tenant_id="t1"))
+        self.service.create(FolderCreate(name="X", tenant_id="t2"))
+        tree_t1 = self.service.get_tree(tenant_id="t1")
+        assert len(tree_t1.roots) == 1