ebk 0.4.4__py3-none-any.whl

ebk/vfs/resolver.py

@@ -0,0 +1,228 @@
+"""Path resolution for the Virtual File System.
+
+Handles path parsing and navigation (cd, ls semantics).
+"""
+
+from pathlib import PurePosixPath
+from typing import Optional, List, Tuple
+
+from ebk.vfs.base import Node, DirectoryNode, SymlinkNode
+
+
+class PathResolver:
+    """Resolves paths in the VFS and handles navigation.
+
+    This class provides the core navigation logic for cd, ls, etc.
+    It handles:
+    - Absolute paths: /books/42/title
+    - Relative paths: ../other, ./files
+    - Special paths: ., .., ~
+    - Symlink resolution
+    """
+
+    def __init__(self, root: DirectoryNode):
+        """Initialize path resolver.
+
+        Args:
+            root: Root node of the VFS
+        """
+        self.root = root
+
+    def resolve(
+        self,
+        path: str,
+        current: DirectoryNode,
+        follow_symlinks: bool = True,
+    ) -> Optional[Node]:
+        """Resolve a path to a node.
+
+        Args:
+            path: Path to resolve (absolute or relative)
+            current: Current working directory
+            follow_symlinks: Whether to follow symlinks
+
+        Returns:
+            Resolved node or None if path doesn't exist
+        """
+        # Handle empty path
+        if not path or path == ".":
+            return current
+
+        # Parse path
+        parts = self._parse_path(path)
+
+        # Start from root or current directory
+        if path.startswith("/"):
+            node = self.root
+        else:
+            node = current
+
+        # Navigate through path parts
+        for part in parts:
+            if part == "." or part == "":
+                continue
+            elif part == "..":
+                # Go to parent
+                if node.parent is not None:
+                    node = node.parent
+                # Stay at root if already at root
+            else:
+                # Navigate to child
+                if not isinstance(node, DirectoryNode):
+                    # Can't cd into a file
+                    return None
+
+                child = node.get_child(part)
+                if child is None:
+                    return None
+
+                # Follow symlinks if requested
+                if follow_symlinks and isinstance(child, SymlinkNode):
+                    child = self.resolve(child.target_path, current, follow_symlinks=True)
+                    if child is None:
+                        return None
+
+                node = child
+
+        return node
+
+    def resolve_directory(
+        self,
+        path: str,
+        current: DirectoryNode,
+    ) -> Optional[DirectoryNode]:
+        """Resolve a path to a directory node.
+
+        Args:
+            path: Path to resolve
+            current: Current working directory
+
+        Returns:
+            Directory node or None if path doesn't exist or isn't a directory
+        """
+        node = self.resolve(path, current)
+        if node is None or not isinstance(node, DirectoryNode):
+            return None
+        return node
+
+    def normalize_path(self, path: str, current: DirectoryNode) -> str:
+        """Normalize a path to absolute form.
+
+        Args:
+            path: Path to normalize
+            current: Current working directory
+
+        Returns:
+            Normalized absolute path
+        """
+        # Resolve to node first
+        node = self.resolve(path, current)
+        if node is None:
+            # Path doesn't exist, do best effort normalization
+            return self._normalize_nonexistent(path, current)
+
+        return node.get_path()
+
+    def complete_path(
+        self,
+        partial: str,
+        current: DirectoryNode,
+    ) -> List[str]:
+        """Get completion candidates for a partial path.
+
+        Used for tab completion.
+
+        Args:
+            partial: Partial path to complete
+            current: Current working directory
+
+        Returns:
+            List of completion candidates
+        """
+        # Split into directory part and filename part
+        if "/" in partial:
+            dir_part, file_part = partial.rsplit("/", 1)
+            if partial.startswith("/"):
+                dir_part = "/" + dir_part if dir_part else "/"
+        else:
+            dir_part = ""
+            file_part = partial
+
+        # Resolve directory
+        if dir_part:
+            dir_node = self.resolve_directory(dir_part, current)
+        else:
+            dir_node = current
+
+        if dir_node is None:
+            return []
+
+        # Get children and filter by prefix
+        children = dir_node.list_children()
+        candidates = []
+
+        for child in children:
+            if child.name.startswith(file_part):
+                if dir_part:
+                    candidates.append(f"{dir_part}/{child.name}")
+                else:
+                    candidates.append(child.name)
+
+                # Add trailing slash for directories
+                if isinstance(child, DirectoryNode):
+                    candidates[-1] += "/"
+
+        return candidates
+
+    def _parse_path(self, path: str) -> List[str]:
+        """Parse a path into parts.
+
+        Args:
+            path: Path to parse
+
+        Returns:
+            List of path components
+        """
+        # Use PurePosixPath for Unix-style path handling
+        posix_path = PurePosixPath(path)
+
+        # Get parts (excluding the root /)
+        parts = posix_path.parts
+        if parts and parts[0] == "/":
+            parts = parts[1:]
+
+        return list(parts)
+
+    def _normalize_nonexistent(self, path: str, current: DirectoryNode) -> str:
+        """Normalize a path that doesn't exist.
+
+        Args:
+            path: Path to normalize
+            current: Current working directory
+
+        Returns:
+            Best-effort normalized path
+        """
+        if path.startswith("/"):
+            # Already absolute
+            return str(PurePosixPath(path))
+
+        # Make relative path absolute
+        current_path = current.get_path()
+        combined = PurePosixPath(current_path) / path
+        return str(combined)
+
+
+class PathError(Exception):
+    """Error resolving a path."""
+    pass
+
+
+class NotADirectoryError(PathError):
+    """Attempted to cd into a non-directory."""
+    pass
+
+
+class NotFoundError(PathError):
+    """Path does not exist."""
+    pass

ebk/vfs_router.py

@@ -0,0 +1,275 @@
+"""VFS REST API Router.
+
+Provides REST endpoints for accessing the Virtual File System,
+enabling programmatic navigation of the library structure.
+
+Endpoints:
+    GET /api/vfs/           - Root directory listing
+    GET /api/vfs/{path:path} - Navigate to path, returns directory/file/symlink info
+
+This allows API consumers to browse the library like a filesystem:
+    - /books/               - List all books
+    - /books/42/            - Book 42's directory
+    - /books/42/title       - Read book title
+    - /books/42/files/      - List book files
+    - /authors/knuth/       - Books by author
+"""
+
+from typing import Any, Dict, List, Optional, Union
+from fastapi import APIRouter, HTTPException, Query
+from pydantic import BaseModel
+
+from ebk.vfs import LibraryVFS, DirectoryNode, FileNode, SymlinkNode
+
+
+# Pydantic models for VFS responses
+class VFSChild(BaseModel):
+    """Child entry in a directory listing."""
+    name: str
+    type: str  # "directory", "file", "symlink", "virtual"
+    info: Dict[str, Any] = {}
+
+
+class VFSDirectoryResponse(BaseModel):
+    """Response for directory nodes."""
+    type: str = "directory"
+    path: str
+    name: str
+    info: Dict[str, Any] = {}
+    children: List[VFSChild] = []
+    children_count: int = 0
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "type": "directory",
+                "path": "/books/42",
+                "name": "42",
+                "info": {"title": "The Art of Computer Programming", "authors": "Donald Knuth"},
+                "children": [
+                    {"name": "title", "type": "file", "info": {}},
+                    {"name": "authors", "type": "file", "info": {}},
+                    {"name": "files", "type": "directory", "info": {}},
+                    {"name": "similar", "type": "virtual", "info": {}},
+                ],
+                "children_count": 4,
+            }
+        }
+
+
+class VFSFileResponse(BaseModel):
+    """Response for file nodes."""
+    type: str = "file"
+    path: str
+    name: str
+    content: str
+    info: Dict[str, Any] = {}
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "type": "file",
+                "path": "/books/42/title",
+                "name": "title",
+                "content": "The Art of Computer Programming",
+                "info": {"size": 34, "writable": False},
+            }
+        }
+
+
+class VFSSymlinkResponse(BaseModel):
+    """Response for symlink nodes."""
+    type: str = "symlink"
+    path: str
+    name: str
+    target: str
+    info: Dict[str, Any] = {}
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "type": "symlink",
+                "path": "/books/42/similar/1",
+                "name": "1",
+                "target": "/books/101",
+                "info": {"title": "Structure and Interpretation..."},
+            }
+        }
+
+
+VFSResponse = Union[VFSDirectoryResponse, VFSFileResponse, VFSSymlinkResponse]
+
+
+# Create router
+router = APIRouter(prefix="/api/vfs", tags=["vfs"])
+
+
+# Module-level VFS instance (initialized when library is set)
+_vfs: Optional[LibraryVFS] = None
+
+
+def get_vfs() -> LibraryVFS:
+    """Get the VFS instance."""
+    if _vfs is None:
+        raise HTTPException(status_code=500, detail="VFS not initialized")
+    return _vfs
+
+
+def set_vfs(vfs: LibraryVFS) -> None:
+    """Set the VFS instance."""
+    global _vfs
+    _vfs = vfs
+
+
+def init_vfs_from_library(library) -> None:
+    """Initialize VFS from a library instance."""
+    global _vfs
+    _vfs = LibraryVFS(library)
+
+
+
+def _build_response(node, path: str, include_content: bool = True) -> VFSResponse:
+    """Build appropriate response for a node."""
+    info = node.get_info()
+
+    if isinstance(node, SymlinkNode):
+        return VFSSymlinkResponse(
+            path=path,
+            name=node.name,
+            target=node.target_path,
+            info={k: v for k, v in info.items() if k not in ("type", "name", "target", "path")},
+        )
+
+    if isinstance(node, FileNode):
+        content = ""
+        if include_content:
+            try:
+                content = node.read_content()
+            except Exception as e:
+                content = f"Error reading content: {e}"
+
+        return VFSFileResponse(
+            path=path,
+            name=node.name,
+            content=content,
+            info={k: v for k, v in info.items() if k not in ("type", "name", "path")},
+        )
+
+    if isinstance(node, DirectoryNode):
+        children = []
+        try:
+            child_nodes = node.list_children()
+            for child in child_nodes:
+                child_info = child.get_info()
+                children.append(VFSChild(
+                    name=child.name,
+                    type=child.node_type.value,
+                    info={k: v for k, v in child_info.items() if k not in ("type", "name", "path")},
+                ))
+        except Exception as e:
+            # Log error but continue
+            pass
+
+        return VFSDirectoryResponse(
+            path=path,
+            name=node.name,
+            info={k: v for k, v in info.items() if k not in ("type", "name", "path", "children_count")},
+            children=children,
+            children_count=len(children),
+        )
+
+    # Fallback for unknown node types
+    raise HTTPException(status_code=500, detail=f"Unknown node type: {type(node)}")
+
+
+@router.get(
+    "/",
+    response_model=VFSDirectoryResponse,
+    summary="VFS Root",
+    description="Get the root directory of the virtual filesystem.",
+    responses={
+        200: {
+            "description": "Root directory listing",
+            "content": {
+                "application/json": {
+                    "example": {
+                        "type": "directory",
+                        "path": "/",
+                        "name": "",
+                        "info": {},
+                        "children": [
+                            {"name": "books", "type": "virtual", "info": {}},
+                            {"name": "authors", "type": "virtual", "info": {}},
+                            {"name": "subjects", "type": "virtual", "info": {}},
+                            {"name": "tags", "type": "virtual", "info": {}},
+                        ],
+                        "children_count": 4,
+                    }
+                }
+            },
+        }
+    },
+)
+async def get_vfs_root():
+    """Get the VFS root directory listing.
+
+    Returns the top-level virtual directories:
+    - /books/ - Browse all books by ID
+    - /authors/ - Browse books by author
+    - /subjects/ - Browse books by subject
+    - /tags/ - Browse books by tag hierarchy
+    """
+    vfs = get_vfs()
+    return _build_response(vfs.root, "/")
+
+
+@router.get(
+    "/{path:path}",
+    response_model=VFSResponse,
+    summary="VFS Path",
+    description="Navigate to a path in the virtual filesystem.",
+    responses={
+        200: {
+            "description": "Node at the specified path (directory, file, or symlink)",
+        },
+        404: {
+            "description": "Path not found",
+        },
+    },
+)
+async def get_vfs_path(
+    path: str,
+    follow_symlinks: bool = Query(True, description="Follow symbolic links to their targets"),
+    include_content: bool = Query(True, description="Include file content in response (for files only)"),
+):
+    """Navigate to a path in the VFS and return its contents.
+
+    For directories, returns the listing of children.
+    For files, returns the content.
+    For symlinks, returns link info (or follows if follow_symlinks=true).
+
+    Examples:
+    - /books/ - List all books
+    - /books/42 - Book 42's directory
+    - /books/42/title - Read book 42's title
+    - /books/42/authors - Read book 42's authors
+    - /books/42/files/ - List book 42's files
+    - /authors/knuth-donald/ - Books by Donald Knuth
+    - /tags/Work/Projects/ - Books tagged Work/Projects
+    """
+    vfs = get_vfs()
+
+    # Normalize path
+    if not path.startswith("/"):
+        path = "/" + path
+
+    # Handle trailing slash consistently
+    clean_path = path.rstrip("/") if path != "/" else path
+
+    # Resolve the path
+    node = vfs.resolver.resolve(clean_path, vfs.root, follow_symlinks=follow_symlinks)
+
+    if node is None:
+        raise HTTPException(status_code=404, detail=f"Path not found: {path}")
+
+    return _build_response(node, node.get_path(), include_content=include_content)

ebk/views/__init__.py

@@ -0,0 +1,32 @@
+"""
+Views DSL for ebk.
+
+A composable, non-destructive system for defining curated subsets of a library
+with optional metadata overrides. Following SICP principles:
+
+- Primitives: all, none, filter, ids, view references
+- Combination: union, intersect, difference
+- Abstraction: named views become new primitives
+- Closure: combining views yields a view
+
+Example:
+    from ebk.views import ViewEvaluator
+
+    evaluator = ViewEvaluator(session)
+
+    # Evaluate a view definition
+    books = evaluator.evaluate({
+        'select': {
+            'intersect': [
+                {'filter': {'subject': 'programming'}},
+                {'filter': {'favorite': True}}
+            ]
+        },
+        'order': {'by': 'title'}
+    })
+"""
+
+from .dsl import ViewEvaluator, TransformedBook
+from .service import ViewService
+
+__all__ = ['ViewEvaluator', 'TransformedBook', 'ViewService']