ebk 0.4.4__py3-none-any.whl

ebk/services/personal_metadata_service.py

@@ -0,0 +1,347 @@
+"""
+Personal metadata service for managing user-specific book data.
+
+Handles ratings, favorites, reading status, progress tracking, and personal tags.
+"""
+
+from typing import List, Optional, Dict, Any
+from datetime import datetime
+import logging
+
+from sqlalchemy.orm import Session
+
+from ..db.models import Book, PersonalMetadata
+
+logger = logging.getLogger(__name__)
+
+
+class PersonalMetadataService:
+    """Service for managing personal metadata for books."""
+
+    def __init__(self, session: Session):
+        """
+        Initialize the personal metadata service.
+
+        Args:
+            session: SQLAlchemy database session
+        """
+        self.session = session
+
+    def get(self, book_id: int) -> Optional[PersonalMetadata]:
+        """
+        Get personal metadata for a book.
+
+        Args:
+            book_id: Book ID
+
+        Returns:
+            PersonalMetadata instance or None if not found
+        """
+        return self.session.query(PersonalMetadata).filter_by(
+            book_id=book_id
+        ).first()
+
+    def get_or_create(self, book_id: int) -> PersonalMetadata:
+        """
+        Get or create personal metadata for a book.
+
+        Args:
+            book_id: Book ID
+
+        Returns:
+            PersonalMetadata instance (created if didn't exist)
+        """
+        personal = self.get(book_id)
+        if not personal:
+            personal = PersonalMetadata(book_id=book_id)
+            self.session.add(personal)
+            self.session.flush()
+        return personal
+
+    def set_rating(self, book_id: int, rating: Optional[float]) -> PersonalMetadata:
+        """
+        Set rating for a book.
+
+        Args:
+            book_id: Book ID
+            rating: Rating value (0-5, or None to clear)
+
+        Returns:
+            Updated PersonalMetadata instance
+        """
+        if rating is not None and (rating < 0 or rating > 5):
+            raise ValueError("Rating must be between 0 and 5")
+
+        personal = self.get_or_create(book_id)
+        personal.rating = rating
+        self.session.commit()
+        logger.debug(f"Set rating for book {book_id}: {rating}")
+        return personal
+
+    def set_favorite(self, book_id: int, is_favorite: bool = True) -> PersonalMetadata:
+        """
+        Mark or unmark a book as favorite.
+
+        Args:
+            book_id: Book ID
+            is_favorite: True to mark as favorite, False to unmark
+
+        Returns:
+            Updated PersonalMetadata instance
+        """
+        personal = self.get_or_create(book_id)
+        personal.favorite = is_favorite
+        self.session.commit()
+        logger.debug(f"Set favorite for book {book_id}: {is_favorite}")
+        return personal
+
+    def set_reading_status(
+        self,
+        book_id: int,
+        status: str,
+        progress: Optional[int] = None,
+    ) -> PersonalMetadata:
+        """
+        Set reading status for a book.
+
+        Args:
+            book_id: Book ID
+            status: Reading status (unread, reading, read, abandoned)
+            progress: Optional reading progress (0-100)
+
+        Returns:
+            Updated PersonalMetadata instance
+        """
+        valid_statuses = {'unread', 'reading', 'read', 'abandoned'}
+        if status not in valid_statuses:
+            raise ValueError(f"Status must be one of: {valid_statuses}")
+
+        if progress is not None and (progress < 0 or progress > 100):
+            raise ValueError("Progress must be between 0 and 100")
+
+        personal = self.get_or_create(book_id)
+        personal.reading_status = status
+
+        if progress is not None:
+            personal.reading_progress = progress
+
+        # Update dates based on status
+        if status == 'reading' and not personal.date_started:
+            personal.date_started = datetime.now()
+        elif status == 'read':
+            personal.date_finished = datetime.now()
+            personal.reading_progress = 100
+
+        self.session.commit()
+        logger.debug(f"Set reading status for book {book_id}: {status}")
+        return personal
+
+    def update_progress(self, book_id: int, progress: int) -> PersonalMetadata:
+        """
+        Update reading progress for a book.
+
+        Args:
+            book_id: Book ID
+            progress: Reading progress percentage (0-100)
+
+        Returns:
+            Updated PersonalMetadata instance
+        """
+        if progress < 0 or progress > 100:
+            raise ValueError("Progress must be between 0 and 100")
+
+        personal = self.get_or_create(book_id)
+        personal.reading_progress = progress
+
+        # Auto-update status based on progress
+        if progress > 0 and personal.reading_status == 'unread':
+            personal.reading_status = 'reading'
+            if not personal.date_started:
+                personal.date_started = datetime.now()
+        elif progress == 100:
+            personal.reading_status = 'read'
+            personal.date_finished = datetime.now()
+
+        self.session.commit()
+        logger.debug(f"Updated progress for book {book_id}: {progress}%")
+        return personal
+
+    def set_owned(self, book_id: int, owned: bool = True) -> PersonalMetadata:
+        """
+        Set whether a book is owned.
+
+        Args:
+            book_id: Book ID
+            owned: True if owned, False if borrowed/library
+
+        Returns:
+            Updated PersonalMetadata instance
+        """
+        personal = self.get_or_create(book_id)
+        personal.owned = owned
+        self.session.commit()
+        logger.debug(f"Set owned for book {book_id}: {owned}")
+        return personal
+
+    def add_personal_tags(self, book_id: int, tags: List[str]) -> PersonalMetadata:
+        """
+        Add personal tags to a book.
+
+        Args:
+            book_id: Book ID
+            tags: List of tag strings to add
+
+        Returns:
+            Updated PersonalMetadata instance
+        """
+        personal = self.get_or_create(book_id)
+        existing_tags = personal.personal_tags or []
+
+        # Add new tags (avoiding duplicates)
+        for tag in tags:
+            if tag and tag not in existing_tags:
+                existing_tags.append(tag)
+
+        personal.personal_tags = existing_tags
+        self.session.commit()
+        logger.debug(f"Added personal tags to book {book_id}: {tags}")
+        return personal
+
+    def remove_personal_tags(self, book_id: int, tags: List[str]) -> PersonalMetadata:
+        """
+        Remove personal tags from a book.
+
+        Args:
+            book_id: Book ID
+            tags: List of tag strings to remove
+
+        Returns:
+            Updated PersonalMetadata instance
+        """
+        personal = self.get(book_id)
+        if not personal or not personal.personal_tags:
+            return personal
+
+        personal.personal_tags = [t for t in personal.personal_tags if t not in tags]
+        self.session.commit()
+        logger.debug(f"Removed personal tags from book {book_id}: {tags}")
+        return personal
+
+    def get_favorites(self) -> List[Book]:
+        """
+        Get all favorite books.
+
+        Returns:
+            List of favorite books
+        """
+        return self.session.query(Book).join(Book.personal).filter(
+            PersonalMetadata.favorite == True
+        ).all()
+
+    def get_by_status(self, status: str) -> List[Book]:
+        """
+        Get books by reading status.
+
+        Args:
+            status: Reading status to filter by
+
+        Returns:
+            List of books with the specified status
+        """
+        return self.session.query(Book).join(Book.personal).filter(
+            PersonalMetadata.reading_status == status
+        ).all()
+
+    def get_by_rating(self, min_rating: float, max_rating: float = 5.0) -> List[Book]:
+        """
+        Get books within a rating range.
+
+        Args:
+            min_rating: Minimum rating (inclusive)
+            max_rating: Maximum rating (inclusive)
+
+        Returns:
+            List of books within the rating range
+        """
+        return self.session.query(Book).join(Book.personal).filter(
+            PersonalMetadata.rating >= min_rating,
+            PersonalMetadata.rating <= max_rating
+        ).order_by(PersonalMetadata.rating.desc()).all()
+
+    def get_stats(self) -> Dict[str, Any]:
+        """
+        Get personal metadata statistics.
+
+        Returns:
+            Dictionary with statistics about personal metadata
+        """
+        from sqlalchemy import func
+
+        stats = {
+            "total_with_metadata": self.session.query(PersonalMetadata).count(),
+            "favorites_count": self.session.query(PersonalMetadata).filter(
+                PersonalMetadata.favorite == True
+            ).count(),
+            "by_status": {},
+            "by_rating": {},
+            "in_queue": self.session.query(PersonalMetadata).filter(
+                PersonalMetadata.queue_position.isnot(None)
+            ).count(),
+        }
+
+        # Count by status
+        status_counts = self.session.query(
+            PersonalMetadata.reading_status,
+            func.count(PersonalMetadata.id)
+        ).group_by(PersonalMetadata.reading_status).all()
+
+        for status, count in status_counts:
+            if status:
+                stats["by_status"][status] = count
+
+        # Count by rating
+        rating_counts = self.session.query(
+            func.round(PersonalMetadata.rating),
+            func.count(PersonalMetadata.id)
+        ).filter(
+            PersonalMetadata.rating.isnot(None)
+        ).group_by(func.round(PersonalMetadata.rating)).all()
+
+        for rating, count in rating_counts:
+            if rating is not None:
+                stats["by_rating"][int(rating)] = count
+
+        # Average rating
+        avg_rating = self.session.query(
+            func.avg(PersonalMetadata.rating)
+        ).filter(PersonalMetadata.rating.isnot(None)).scalar()
+        stats["average_rating"] = round(avg_rating, 2) if avg_rating else None
+
+        return stats
+
+    def to_dict(self, book_id: int) -> Optional[Dict[str, Any]]:
+        """
+        Get personal metadata as a dictionary.
+
+        Args:
+            book_id: Book ID
+
+        Returns:
+            Dictionary representation or None if no metadata
+        """
+        personal = self.get(book_id)
+        if not personal:
+            return None
+
+        return {
+            "rating": personal.rating,
+            "is_favorite": personal.favorite,
+            "reading_status": personal.reading_status,
+            "reading_progress": personal.reading_progress,
+            "owned": personal.owned,
+            "queue_position": personal.queue_position,
+            "personal_tags": personal.personal_tags or [],
+            "date_added": personal.date_added.isoformat() if personal.date_added else None,
+            "date_started": personal.date_started.isoformat() if personal.date_started else None,
+            "date_finished": personal.date_finished.isoformat() if personal.date_finished else None,
+        }

ebk/services/queue_service.py

@@ -0,0 +1,253 @@
+"""
+Reading queue service for managing the reading queue.
+
+Provides operations for adding, removing, reordering, and querying
+books in the reading queue.
+"""
+
+from typing import List, Optional
+import logging
+
+from sqlalchemy import func
+from sqlalchemy.orm import Session
+
+from ..db.models import Book, PersonalMetadata
+
+logger = logging.getLogger(__name__)
+
+
+class ReadingQueueService:
+    """Service for managing the reading queue."""
+
+    def __init__(self, session: Session):
+        """
+        Initialize the reading queue service.
+
+        Args:
+            session: SQLAlchemy database session
+        """
+        self.session = session
+
+    def get_queue(self) -> List[Book]:
+        """
+        Get all books in the reading queue, ordered by position.
+
+        Returns:
+            List of books in queue order
+        """
+        return self.session.query(Book).join(Book.personal).filter(
+            PersonalMetadata.queue_position.isnot(None)
+        ).order_by(PersonalMetadata.queue_position).all()
+
+    def get_next(self) -> Optional[Book]:
+        """
+        Get the next book in the reading queue (position 1).
+
+        Returns:
+            The book at the top of the queue, or None if queue is empty
+        """
+        return self.session.query(Book).join(Book.personal).filter(
+            PersonalMetadata.queue_position == 1
+        ).first()
+
+    def get_position(self, book_id: int) -> Optional[int]:
+        """
+        Get the position of a book in the queue.
+
+        Args:
+            book_id: Book ID to check
+
+        Returns:
+            Queue position (1-based) or None if not in queue
+        """
+        personal = self.session.query(PersonalMetadata).filter_by(
+            book_id=book_id
+        ).first()
+
+        if personal:
+            return personal.queue_position
+        return None
+
+    def is_in_queue(self, book_id: int) -> bool:
+        """
+        Check if a book is in the queue.
+
+        Args:
+            book_id: Book ID to check
+
+        Returns:
+            True if book is in queue
+        """
+        return self.get_position(book_id) is not None
+
+    def add(self, book_id: int, position: Optional[int] = None) -> int:
+        """
+        Add a book to the reading queue.
+
+        Args:
+            book_id: Book ID to add
+            position: Position in queue (1-based). If None, adds to end.
+
+        Returns:
+            The position where the book was added
+        """
+        personal = self.session.query(PersonalMetadata).filter_by(
+            book_id=book_id
+        ).first()
+
+        if not personal:
+            personal = PersonalMetadata(book_id=book_id)
+            self.session.add(personal)
+            self.session.flush()
+
+        # If already in queue, just reorder
+        if personal.queue_position is not None:
+            if position is not None:
+                self.reorder(book_id, position)
+            return personal.queue_position
+
+        # Get current max position
+        max_pos = self.session.query(
+            func.max(PersonalMetadata.queue_position)
+        ).scalar() or 0
+
+        if position is None:
+            # Add to end
+            personal.queue_position = max_pos + 1
+        else:
+            # Insert at specific position, shift others down
+            position = max(1, position)
+            self.session.query(PersonalMetadata).filter(
+                PersonalMetadata.queue_position >= position,
+                PersonalMetadata.queue_position.isnot(None)
+            ).update({
+                PersonalMetadata.queue_position: PersonalMetadata.queue_position + 1
+            })
+            personal.queue_position = position
+
+        self.session.commit()
+        logger.info(f"Added book {book_id} to queue at position {personal.queue_position}")
+        return personal.queue_position
+
+    def remove(self, book_id: int) -> bool:
+        """
+        Remove a book from the reading queue.
+
+        Args:
+            book_id: Book ID to remove
+
+        Returns:
+            True if book was removed, False if it wasn't in queue
+        """
+        personal = self.session.query(PersonalMetadata).filter_by(
+            book_id=book_id
+        ).first()
+
+        if not personal or personal.queue_position is None:
+            return False
+
+        old_position = personal.queue_position
+        personal.queue_position = None
+
+        # Shift other items up to fill gap
+        self.session.query(PersonalMetadata).filter(
+            PersonalMetadata.queue_position > old_position
+        ).update({
+            PersonalMetadata.queue_position: PersonalMetadata.queue_position - 1
+        })
+
+        self.session.commit()
+        logger.info(f"Removed book {book_id} from queue")
+        return True
+
+    def reorder(self, book_id: int, new_position: int) -> bool:
+        """
+        Move a book to a new position in the queue.
+
+        Args:
+            book_id: Book ID to move
+            new_position: New position (1-based)
+
+        Returns:
+            True if book was reordered, False if it wasn't in queue
+        """
+        personal = self.session.query(PersonalMetadata).filter_by(
+            book_id=book_id
+        ).first()
+
+        if not personal or personal.queue_position is None:
+            # Not in queue, add it
+            self.add(book_id, new_position)
+            return True
+
+        old_position = personal.queue_position
+        new_position = max(1, new_position)
+
+        if old_position == new_position:
+            return True
+
+        if old_position < new_position:
+            # Moving down: shift items between old and new up
+            self.session.query(PersonalMetadata).filter(
+                PersonalMetadata.queue_position > old_position,
+                PersonalMetadata.queue_position <= new_position,
+                PersonalMetadata.queue_position.isnot(None)
+            ).update({
+                PersonalMetadata.queue_position: PersonalMetadata.queue_position - 1
+            })
+        else:
+            # Moving up: shift items between new and old down
+            self.session.query(PersonalMetadata).filter(
+                PersonalMetadata.queue_position >= new_position,
+                PersonalMetadata.queue_position < old_position,
+                PersonalMetadata.queue_position.isnot(None)
+            ).update({
+                PersonalMetadata.queue_position: PersonalMetadata.queue_position + 1
+            })
+
+        personal.queue_position = new_position
+        self.session.commit()
+        logger.info(f"Moved book {book_id} from position {old_position} to {new_position}")
+        return True
+
+    def clear(self) -> int:
+        """
+        Clear all books from the reading queue.
+
+        Returns:
+            Number of books removed from queue
+        """
+        count = self.session.query(PersonalMetadata).filter(
+            PersonalMetadata.queue_position.isnot(None)
+        ).count()
+
+        self.session.query(PersonalMetadata).filter(
+            PersonalMetadata.queue_position.isnot(None)
+        ).update({PersonalMetadata.queue_position: None})
+
+        self.session.commit()
+        logger.info(f"Cleared reading queue ({count} items)")
+        return count
+
+    def count(self) -> int:
+        """
+        Get the number of books in the queue.
+
+        Returns:
+            Number of books in queue
+        """
+        return self.session.query(PersonalMetadata).filter(
+            PersonalMetadata.queue_position.isnot(None)
+        ).count()
+
+    def pop_next(self) -> Optional[Book]:
+        """
+        Remove and return the next book from the queue.
+
+        Returns:
+            The book that was at position 1, or None if queue is empty
+        """
+        book = self.get_next()
+        if book:
+            self.remove(book.id)
+        return book