ebk 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

ebk/vfs/base.py

@@ -0,0 +1,301 @@
+"""Base classes for the Virtual File System.
+
+The VFS maps the library database to a filesystem-like structure
+that can be navigated with shell commands (cd, ls, cat, etc.).
+
+Architecture:
+    - Node: Base class for all VFS nodes
+    - DirectoryNode: Nodes that can contain children (cd into them)
+    - FileNode: Leaf nodes with content (cat them)
+    - VirtualNode: Dynamically computed nodes (e.g., similar books)
+"""
+
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Dict, List, Optional, Any
+from datetime import datetime
+
+
+class NodeType(Enum):
+    """Type of VFS node."""
+    DIRECTORY = "directory"
+    FILE = "file"
+    VIRTUAL = "virtual"
+    SYMLINK = "symlink"
+
+
+class Node(ABC):
+    """Base class for all VFS nodes.
+
+    A Node represents an entry in the virtual filesystem. It can be
+    a directory (navigable), a file (readable), or something virtual
+    (dynamically computed).
+
+    Attributes:
+        name: The name of this node (e.g., "title", "books", "42")
+        parent: Parent directory node (None for root)
+        node_type: Type of node (directory, file, virtual, symlink)
+    """
+
+    def __init__(
+        self,
+        name: str,
+        parent: Optional['DirectoryNode'] = None,
+        node_type: NodeType = NodeType.FILE,
+    ):
+        """Initialize a VFS node.
+
+        Args:
+            name: Name of this node
+            parent: Parent directory (None for root)
+            node_type: Type of node
+        """
+        self.name = name
+        self.parent = parent
+        self.node_type = node_type
+        self._metadata: Dict[str, Any] = {}
+
+    @abstractmethod
+    def get_info(self) -> Dict[str, Any]:
+        """Get metadata about this node for display.
+
+        Returns:
+            Dict with keys like: size, modified, type, description
+        """
+        pass
+
+    def get_path(self) -> str:
+        """Get absolute path to this node.
+
+        Returns:
+            Path like /books/42/title
+        """
+        if self.parent is None:
+            return "/"
+
+        parts = []
+        node = self
+        while node.parent is not None:
+            parts.append(node.name)
+            node = node.parent
+
+        if not parts:
+            return "/"
+
+        return "/" + "/".join(reversed(parts))
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(name='{self.name}', path='{self.get_path()}')"
+
+
+class DirectoryNode(Node):
+    """A directory node that can contain children.
+
+    Directory nodes can be navigated into with `cd` and their
+    children can be listed with `ls`.
+
+    Children can be:
+    - Static: Fixed set of children
+    - Dynamic: Children computed on-demand (e.g., book list from DB)
+    """
+
+    def __init__(self, name: str, parent: Optional['DirectoryNode'] = None):
+        """Initialize a directory node.
+
+        Args:
+            name: Name of this directory
+            parent: Parent directory
+        """
+        super().__init__(name, parent, NodeType.DIRECTORY)
+        self._children: Dict[str, Node] = {}
+
+    @abstractmethod
+    def list_children(self) -> List[Node]:
+        """List all children of this directory.
+
+        This may compute children dynamically from the database.
+
+        Returns:
+            List of child nodes
+        """
+        pass
+
+    @abstractmethod
+    def get_child(self, name: str) -> Optional[Node]:
+        """Get a child node by name.
+
+        Args:
+            name: Name of child node
+
+        Returns:
+            Child node or None if not found
+        """
+        pass
+
+    def get_info(self) -> Dict[str, Any]:
+        """Get directory metadata.
+
+        Returns:
+            Dict with directory information
+        """
+        children = self.list_children()
+        return {
+            "type": "directory",
+            "name": self.name,
+            "children_count": len(children),
+            "path": self.get_path(),
+        }
+
+
+class FileNode(Node):
+    """A file node with readable content.
+
+    File nodes represent data that can be read with `cat`.
+    Examples: book title, description, full text, etc.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        parent: Optional[DirectoryNode] = None,
+        size: Optional[int] = None,
+    ):
+        """Initialize a file node.
+
+        Args:
+            name: Name of this file
+            parent: Parent directory
+            size: Size in bytes (if known)
+        """
+        super().__init__(name, parent, NodeType.FILE)
+        self._size = size
+        self._content_cache: Optional[str] = None
+
+    @abstractmethod
+    def read_content(self) -> str:
+        """Read the content of this file.
+
+        Returns:
+            File content as string
+        """
+        pass
+
+    def write_content(self, content: str) -> None:
+        """Write content to this file.
+
+        Args:
+            content: Content to write
+
+        Raises:
+            NotImplementedError: If the file is read-only
+        """
+        raise NotImplementedError(f"File '{self.name}' is read-only")
+
+    def is_writable(self) -> bool:
+        """Check if this file is writable.
+
+        Returns:
+            True if file supports writing, False otherwise
+        """
+        # By default, files are read-only unless they override write_content
+        try:
+            # Try calling write_content with empty string to see if it raises NotImplementedError
+            # This is a bit hacky but works
+            return hasattr(self.__class__, 'write_content') and \
+                   self.__class__.write_content != FileNode.write_content
+        except:
+            return False
+
+    def get_info(self) -> Dict[str, Any]:
+        """Get file metadata.
+
+        Returns:
+            Dict with file information
+        """
+        return {
+            "type": "file",
+            "name": self.name,
+            "size": self._size,
+            "path": self.get_path(),
+            "writable": self.is_writable(),
+        }
+
+
+class VirtualNode(DirectoryNode):
+    """A virtual directory with dynamically computed children.
+
+    Virtual nodes don't have a fixed set of children - they compute
+    them on-demand from the database or other sources.
+
+    Examples:
+    - /books/ - Lists all books from DB
+    - /books/42/similar/ - Computes similar books on-demand
+    - /authors/ - Lists all authors from DB
+    """
+
+    def __init__(self, name: str, parent: Optional[DirectoryNode] = None):
+        """Initialize a virtual directory node.
+
+        Args:
+            name: Name of this directory
+            parent: Parent directory
+        """
+        super().__init__(name, parent)
+        self.node_type = NodeType.VIRTUAL
+
+    def get_info(self) -> Dict[str, Any]:
+        """Get virtual directory metadata.
+
+        Returns:
+            Dict with virtual directory information
+        """
+        info = super().get_info()
+        info["type"] = "virtual"
+        return info
+
+
+class SymlinkNode(Node):
+    """A symbolic link pointing to another node.
+
+    Used for creating convenient shortcuts, like similar books
+    appearing as links in /books/42/similar/.
+
+    Attributes:
+        target_path: Path to the target node
+        metadata: Optional metadata dict to include in get_info()
+    """
+
+    def __init__(
+        self,
+        name: str,
+        target_path: str,
+        parent: Optional[DirectoryNode] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ):
+        """Initialize a symlink node.
+
+        Args:
+            name: Name of this symlink
+            target_path: Path to target node
+            parent: Parent directory
+            metadata: Optional metadata to include in get_info()
+        """
+        super().__init__(name, parent, NodeType.SYMLINK)
+        self.target_path = target_path
+        self.metadata = metadata or {}
+
+    def get_info(self) -> Dict[str, Any]:
+        """Get symlink metadata.
+
+        Returns:
+            Dict with symlink information plus any provided metadata
+        """
+        info = {
+            "type": "symlink",
+            "name": self.name,
+            "target": self.target_path,
+            "path": self.get_path(),
+        }
+        # Merge in any provided metadata
+        info.update(self.metadata)
+        return info

ebk/vfs/library_vfs.py

@@ -0,0 +1,124 @@
+"""Main LibraryVFS class - entry point for VFS access."""
+
+from pathlib import Path as FilePath
+
+from ebk.library_db import Library
+from ebk.vfs.base import DirectoryNode, Node
+from ebk.vfs.resolver import PathResolver
+from ebk.vfs.nodes import RootNode
+
+
+class LibraryVFS:
+    """Virtual File System for a library.
+
+    This is the main entry point for accessing the VFS. It creates
+    the root node and provides a resolver for path navigation.
+
+    Usage:
+        >>> lib = Library.open("/path/to/library")
+        >>> vfs = LibraryVFS(lib)
+        >>>
+        >>> # Navigate using resolver
+        >>> books_dir = vfs.resolver.resolve("/books", vfs.root)
+        >>> book_node = vfs.resolver.resolve("/books/42", vfs.root)
+        >>>
+        >>> # List children
+        >>> children = books_dir.list_children()
+        >>>
+        >>> # Read file content
+        >>> title_node = vfs.resolver.resolve("/books/42/title", vfs.root)
+        >>> if isinstance(title_node, FileNode):
+        >>>     print(title_node.read_content())
+    """
+
+    def __init__(self, library: Library):
+        """Initialize VFS for a library.
+
+        Args:
+            library: Library instance
+        """
+        self.library = library
+        self.root = RootNode(library)
+        self.resolver = PathResolver(self.root)
+        self.current = self.root  # Current working directory
+
+    def cd(self, path: str) -> bool:
+        """Change current directory.
+
+        Args:
+            path: Path to navigate to
+
+        Returns:
+            True if successful, False otherwise
+        """
+        new_dir = self.resolver.resolve_directory(path, self.current)
+        if new_dir is None:
+            return False
+
+        self.current = new_dir
+        return True
+
+    def pwd(self) -> str:
+        """Get current working directory path.
+
+        Returns:
+            Current path
+        """
+        return self.current.get_path()
+
+    def ls(self, path: str = ".") -> list:
+        """List children of a directory.
+
+        Args:
+            path: Path to list (default: current directory)
+
+        Returns:
+            List of nodes
+        """
+        node = self.resolver.resolve(path, self.current)
+        if node is None or not isinstance(node, DirectoryNode):
+            return []
+
+        return node.list_children()
+
+    def cat(self, path: str) -> str:
+        """Read content of a file node.
+
+        Args:
+            path: Path to file
+
+        Returns:
+            File content or error message
+        """
+        from ebk.vfs.base import FileNode
+
+        node = self.resolver.resolve(path, self.current)
+        if node is None:
+            return f"cat: {path}: No such file or directory"
+
+        if not isinstance(node, FileNode):
+            return f"cat: {path}: Is a directory"
+
+        return node.read_content()
+
+    def get_node(self, path: str) -> Node:
+        """Resolve a path to a node.
+
+        Args:
+            path: Path to resolve
+
+        Returns:
+            Resolved node or None
+        """
+        return self.resolver.resolve(path, self.current)
+
+    def complete(self, partial: str) -> list:
+        """Get tab completion candidates.
+
+        Args:
+            partial: Partial path
+
+        Returns:
+            List of completion candidates
+        """
+        return self.resolver.complete_path(partial, self.current)

ebk/vfs/nodes/__init__.py

@@ -0,0 +1,54 @@
+"""VFS node implementations."""
+
+from ebk.vfs.nodes.root import RootNode
+from ebk.vfs.nodes.books import BooksDirectoryNode, BookNode
+from ebk.vfs.nodes.metadata import (
+    TitleFileNode,
+    AuthorsFileNode,
+    SubjectsFileNode,
+    DescriptionFileNode,
+    TextFileNode,
+    YearFileNode,
+    LanguageFileNode,
+    PublisherFileNode,
+    MetadataFileNode,
+)
+from ebk.vfs.nodes.files import FilesDirectoryNode, PhysicalFileNode
+from ebk.vfs.nodes.similar import SimilarDirectoryNode, SimilarBookSymlink
+from ebk.vfs.nodes.authors import AuthorsDirectoryNode, AuthorNode
+from ebk.vfs.nodes.subjects import SubjectsDirectoryNode, SubjectNode
+from ebk.vfs.nodes.tags import (
+    TagsDirectoryNode,
+    TagNode,
+    TagDescriptionFile,
+    TagColorFile,
+    TagStatsFile,
+)
+
+__all__ = [
+    "RootNode",
+    "BooksDirectoryNode",
+    "BookNode",
+    "TitleFileNode",
+    "AuthorsFileNode",
+    "SubjectsFileNode",
+    "DescriptionFileNode",
+    "TextFileNode",
+    "YearFileNode",
+    "LanguageFileNode",
+    "PublisherFileNode",
+    "MetadataFileNode",
+    "FilesDirectoryNode",
+    "PhysicalFileNode",
+    "SimilarDirectoryNode",
+    "SimilarBookSymlink",
+    "AuthorsDirectoryNode",
+    "AuthorNode",
+    "SubjectsDirectoryNode",
+    "SubjectNode",
+    "TagsDirectoryNode",
+    "TagNode",
+    "TagDescriptionFile",
+    "TagColorFile",
+    "TagStatsFile",
+]

ebk/vfs/nodes/authors.py

@@ -0,0 +1,196 @@
+"""Author-related VFS nodes."""
+
+from typing import List, Optional, Dict, Any
+
+from ebk.vfs.base import VirtualNode, DirectoryNode, SymlinkNode, Node
+from ebk.library_db import Library
+from ebk.db.models import Author
+
+
+class AuthorsDirectoryNode(VirtualNode):
+    """/authors/ - Virtual directory listing all authors.
+
+    Each child is an AuthorNode representing books by that author.
+    """
+
+    def __init__(self, library: Library, parent: Optional[DirectoryNode] = None):
+        """Initialize authors directory.
+
+        Args:
+            library: Library instance
+            parent: Parent node (usually root)
+        """
+        super().__init__(name="authors", parent=parent)
+        self.library = library
+
+    def list_children(self) -> List[Node]:
+        """List all authors.
+
+        Returns:
+            List of AuthorNode instances
+        """
+        # Query all authors from database
+        # For now, we'll get unique authors from books
+        authors_query = self.library.session.query(Author).all()
+
+        author_nodes = []
+        for author in authors_query:
+            # Create a slug from author name
+            slug = self._make_slug(author.name)
+            node = AuthorNode(author, slug, self.library, parent=self)
+            author_nodes.append(node)
+
+        return author_nodes
+
+    def get_child(self, name: str) -> Optional[Node]:
+        """Get an author by slug.
+
+        Args:
+            name: Author slug (e.g., "knuth-donald")
+
+        Returns:
+            AuthorNode or None
+        """
+        # Try to find author by matching slug
+        authors = self.library.session.query(Author).all()
+
+        for author in authors:
+            slug = self._make_slug(author.name)
+            if slug == name:
+                return AuthorNode(author, slug, self.library, parent=self)
+
+        return None
+
+    def _make_slug(self, name: str) -> str:
+        """Convert author name to filesystem-safe slug.
+
+        Args:
+            name: Author name
+
+        Returns:
+            Slugified name (e.g., "Donald Knuth" -> "knuth-donald")
+        """
+        # Simple slugification: lowercase, replace spaces with hyphens
+        # Reverse name order (Last, First -> first-last)
+        parts = name.lower().split()
+        if len(parts) >= 2:
+            # Assume "First Last" or "Last, First"
+            if "," in name:
+                # "Last, First" format
+                slug = "-".join(reversed([p.strip(",") for p in parts]))
+            else:
+                # "First Last" format - reverse to "last-first"
+                slug = "-".join(reversed(parts))
+        else:
+            slug = "-".join(parts)
+
+        # Remove special characters
+        slug = "".join(c for c in slug if c.isalnum() or c == "-")
+        return slug
+
+    def get_info(self) -> Dict[str, Any]:
+        """Get authors directory info.
+
+        Returns:
+            Dict with directory information
+        """
+        total = self.library.session.query(Author).count()
+        return {
+            "type": "virtual",
+            "name": "authors",
+            "total_authors": total,
+            "path": self.get_path(),
+        }
+
+
+class AuthorNode(VirtualNode):
+    """/authors/knuth-donald/ - Books by a specific author.
+
+    Contains symlinks to books by this author.
+    """
+
+    def __init__(
+        self,
+        author: Author,
+        slug: str,
+        library: Library,
+        parent: Optional[DirectoryNode] = None,
+    ):
+        """Initialize author node.
+
+        Args:
+            author: Author database model
+            slug: Author slug for URL
+            library: Library instance
+            parent: Parent node (usually AuthorsDirectoryNode)
+        """
+        super().__init__(name=slug, parent=parent)
+        self.author = author
+        self.library = library
+
+    def list_children(self) -> List[Node]:
+        """List books by this author as symlinks.
+
+        Returns:
+            List of SymlinkNode instances
+        """
+        symlinks = []
+        for book in self.author.books:
+            target_path = f"/books/{book.id}"
+            name = str(book.id)
+
+            # Include book metadata for display
+            metadata = {
+                "title": book.title or "Untitled",
+            }
+            if book.authors:
+                metadata["author"] = ", ".join([a.name for a in book.authors])
+
+            symlink = SymlinkNode(name, target_path, parent=self, metadata=metadata)
+            symlinks.append(symlink)
+
+        return symlinks
+
+    def get_child(self, name: str) -> Optional[Node]:
+        """Get a book symlink by ID.
+
+        Args:
+            name: Book ID as string
+
+        Returns:
+            SymlinkNode or None
+        """
+        try:
+            book_id = int(name)
+        except ValueError:
+            return None
+
+        # Check if this book is by this author
+        for book in self.author.books:
+            if book.id == book_id:
+                target_path = f"/books/{book.id}"
+
+                # Include book metadata for display
+                metadata = {
+                    "title": book.title or "Untitled",
+                }
+                if book.authors:
+                    metadata["author"] = ", ".join([a.name for a in book.authors])
+
+                return SymlinkNode(name, target_path, parent=self, metadata=metadata)
+
+        return None
+
+    def get_info(self) -> Dict[str, Any]:
+        """Get author node info.
+
+        Returns:
+            Dict with author information
+        """
+        return {
+            "type": "virtual",
+            "name": self.name,
+            "author": self.author.name,
+            "book_count": len(self.author.books),
+            "path": self.get_path(),
+        }