cloudnoteslib 0.1.0__py3-none-any.whl

cloudnoteslib/exporters/markdown_exporter.py

@@ -0,0 +1,28 @@
+"""
+cloudnoteslib.exporters.markdown_exporter — Markdown Exporter.
+"""
+
+from .base import NoteExporter
+from ..models.note_collection import NoteCollection
+
+
+class MarkdownExporter(NoteExporter):
+    """Exports NoteCollection to a single Markdown document."""
+    
+    def export(self, collection: NoteCollection) -> str:
+        lines = ["# Exported Notes", ""]
+        
+        for note in collection:
+            lines.append(f"## {note.title}")
+            lines.append(f"**Date:** {note.created_at.strftime('%Y-%m-%d %H:%M')}")
+            if note.tags:
+                lines.append(f"**Tags:** {', '.join(note.tags)}")
+            lines.append("")
+            lines.append(note.content)
+            lines.append("\n---\n")
+            
+        return "\n".join(lines)
+        
+    @property
+    def extension(self) -> str:
+        return "md"

cloudnoteslib/models/__init__.py

@@ -0,0 +1,18 @@
+"""
+cloudnoteslib.models — Core data models for the Cloud Notes library.
+
+This package contains the fundamental data structures used throughout
+the library. Each model demonstrates OOP Encapsulation through private
+attributes and controlled @property accessors.
+
+Exports:
+    Note: Immutable note with content analysis properties.
+    Tag: Lightweight tag model for categorization.
+    NoteCollection: Iterable container with aggregate operations.
+"""
+
+from .note import Note
+from .tag import Tag
+from .note_collection import NoteCollection
+
+__all__ = ["Note", "Tag", "NoteCollection"]

cloudnoteslib/models/note.py

@@ -0,0 +1,323 @@
+"""
+cloudnoteslib.models.note — Note Data Model.
+
+Demonstrates OOP ENCAPSULATION:
+    - All internal attributes are private (prefixed with _)
+    - Controlled access through @property decorators
+    - Computed properties (reading_time, word_count) derive from internal state
+    - Immutable fields (created_at) cannot be modified after construction
+
+This model represents a single note in the system. It is framework-agnostic
+and can be used with any backend (FastAPI, Flask, Django).
+
+Example:
+    >>> note = Note(title="Meeting Notes", content="Discussed project timeline...")
+    >>> note.word_count
+    3
+    >>> note.reading_time
+    0.0
+    >>> note.to_dict()
+    {'title': 'Meeting Notes', 'content': 'Discussed project timeline...', ...}
+"""
+
+from datetime import datetime
+from typing import List, Optional
+import re
+import hashlib
+
+
+class Note:
+    """
+    Core Note model with encapsulated attributes and computed properties.
+
+    OOP Principles:
+        - ENCAPSULATION: Private attributes (_title, _content, _tags) with
+          @property accessors. External code cannot directly mutate internal
+          state without going through setters that enforce validation.
+        - COMPUTED PROPERTIES: word_count, reading_time, char_count, and
+          summary are derived automatically from the content.
+
+    Attributes:
+        title (str): The note title (1-200 characters).
+        content (str): The note body text.
+        tags (list): List of tag strings for categorization.
+        is_pinned (bool): Whether the note is pinned/starred.
+        is_archived (bool): Whether the note is archived.
+        created_at (datetime): Immutable creation timestamp.
+        updated_at (datetime): Last modification timestamp.
+        note_id (int, optional): Database ID for persistence mapping.
+
+    Example:
+        >>> note = Note("Shopping List", "Milk, Eggs, Bread", tags=["personal"])
+        >>> note.title
+        'Shopping List'
+        >>> note.word_count
+        3
+        >>> note.is_pinned
+        False
+    """
+
+    # Class-level constants
+    MAX_TITLE_LENGTH = 200
+    MAX_CONTENT_LENGTH = 50000
+    AVG_READING_SPEED_WPM = 200  # Words per minute
+
+    def __init__(
+        self,
+        title: str,
+        content: str,
+        tags: Optional[List[str]] = None,
+        is_pinned: bool = False,
+        is_archived: bool = False,
+        note_id: Optional[int] = None,
+        created_at: Optional[datetime] = None,
+        updated_at: Optional[datetime] = None,
+    ):
+        """
+        Initialize a Note instance.
+
+        Args:
+            title: Note title (must be 1-200 characters).
+            content: Note body text (max 50,000 characters).
+            tags: Optional list of tag strings.
+            is_pinned: Whether the note is pinned. Defaults to False.
+            is_archived: Whether the note is archived. Defaults to False.
+            note_id: Optional database ID.
+            created_at: Optional creation timestamp (auto-set if None).
+            updated_at: Optional update timestamp (auto-set if None).
+
+        Raises:
+            ValueError: If title is empty or exceeds MAX_TITLE_LENGTH.
+            ValueError: If content exceeds MAX_CONTENT_LENGTH.
+        """
+        # Validate inputs
+        if not title or not title.strip():
+            raise ValueError("Note title cannot be empty.")
+        if len(title) > self.MAX_TITLE_LENGTH:
+            raise ValueError(
+                f"Title exceeds maximum length of {self.MAX_TITLE_LENGTH} characters."
+            )
+        if len(content) > self.MAX_CONTENT_LENGTH:
+            raise ValueError(
+                f"Content exceeds maximum length of {self.MAX_CONTENT_LENGTH} characters."
+            )
+
+        # Private attributes (ENCAPSULATION)
+        self._note_id = note_id
+        self._title = title.strip()
+        self._content = content
+        self._tags = [t.strip().lower() for t in (tags or []) if t.strip()]
+        self._is_pinned = is_pinned
+        self._is_archived = is_archived
+        self._created_at = created_at or datetime.utcnow()
+        self._updated_at = updated_at or datetime.utcnow()
+
+    # ─── Read-Only Properties (ENCAPSULATION) ───
+
+    @property
+    def note_id(self) -> Optional[int]:
+        """Database identifier. Read-only after construction."""
+        return self._note_id
+
+    @property
+    def title(self) -> str:
+        """Note title. Validated on set to ensure non-empty and within length."""
+        return self._title
+
+    @title.setter
+    def title(self, value: str):
+        """Set note title with validation."""
+        if not value or not value.strip():
+            raise ValueError("Note title cannot be empty.")
+        if len(value) > self.MAX_TITLE_LENGTH:
+            raise ValueError(
+                f"Title exceeds maximum length of {self.MAX_TITLE_LENGTH} characters."
+            )
+        self._title = value.strip()
+        self._updated_at = datetime.utcnow()
+
+    @property
+    def content(self) -> str:
+        """Note body text. Updates the modified timestamp on change."""
+        return self._content
+
+    @content.setter
+    def content(self, value: str):
+        """Set note content with validation and timestamp update."""
+        if len(value) > self.MAX_CONTENT_LENGTH:
+            raise ValueError(
+                f"Content exceeds maximum length of {self.MAX_CONTENT_LENGTH} characters."
+            )
+        self._content = value
+        self._updated_at = datetime.utcnow()
+
+    @property
+    def tags(self) -> List[str]:
+        """List of tags. Returns a copy to prevent external mutation."""
+        return self._tags.copy()
+
+    @property
+    def is_pinned(self) -> bool:
+        """Whether this note is pinned/starred."""
+        return self._is_pinned
+
+    @is_pinned.setter
+    def is_pinned(self, value: bool):
+        self._is_pinned = bool(value)
+        self._updated_at = datetime.utcnow()
+
+    @property
+    def is_archived(self) -> bool:
+        """Whether this note is archived."""
+        return self._is_archived
+
+    @is_archived.setter
+    def is_archived(self, value: bool):
+        self._is_archived = bool(value)
+        self._updated_at = datetime.utcnow()
+
+    @property
+    def created_at(self) -> datetime:
+        """Immutable creation timestamp. Cannot be modified."""
+        return self._created_at
+
+    @property
+    def updated_at(self) -> datetime:
+        """Last modification timestamp. Auto-updates on changes."""
+        return self._updated_at
+
+    # ─── Computed Properties (derived from internal state) ───
+
+    @property
+    def word_count(self) -> int:
+        """Count of words in the note content."""
+        if not self._content.strip():
+            return 0
+        return len(self._content.split())
+
+    @property
+    def char_count(self) -> int:
+        """Count of characters in the note content (excluding whitespace)."""
+        return len(self._content.replace(" ", "").replace("\n", ""))
+
+    @property
+    def sentence_count(self) -> int:
+        """Approximate count of sentences (split by . ! ? endings)."""
+        if not self._content.strip():
+            return 0
+        sentences = re.split(r'[.!?]+', self._content.strip())
+        return len([s for s in sentences if s.strip()])
+
+    @property
+    def reading_time(self) -> float:
+        """Estimated reading time in minutes (based on 200 WPM average)."""
+        return round(self.word_count / self.AVG_READING_SPEED_WPM, 1)
+
+    @property
+    def summary(self) -> str:
+        """Auto-generated summary: first 150 characters of content."""
+        if len(self._content) <= 150:
+            return self._content
+        return self._content[:150].rsplit(" ", 1)[0] + "..."
+
+    @property
+    def content_hash(self) -> str:
+        """SHA-256 hash of the content for integrity verification."""
+        return hashlib.sha256(self._content.encode("utf-8")).hexdigest()
+
+    # ─── Public Methods ───
+
+    def add_tag(self, tag: str) -> None:
+        """
+        Add a tag to this note (case-insensitive, no duplicates).
+
+        Args:
+            tag: Tag string to add.
+        """
+        normalized = tag.strip().lower()
+        if normalized and normalized not in self._tags:
+            self._tags.append(normalized)
+            self._updated_at = datetime.utcnow()
+
+    def remove_tag(self, tag: str) -> bool:
+        """
+        Remove a tag from this note.
+
+        Args:
+            tag: Tag string to remove.
+
+        Returns:
+            True if the tag was removed, False if it wasn't found.
+        """
+        normalized = tag.strip().lower()
+        if normalized in self._tags:
+            self._tags.remove(normalized)
+            self._updated_at = datetime.utcnow()
+            return True
+        return False
+
+    def has_tag(self, tag: str) -> bool:
+        """Check if the note has a specific tag."""
+        return tag.strip().lower() in self._tags
+
+    def to_dict(self) -> dict:
+        """
+        Serialize the note to a dictionary for API responses.
+
+        Returns:
+            dict: Complete note data including computed properties.
+        """
+        return {
+            "note_id": self._note_id,
+            "title": self._title,
+            "content": self._content,
+            "tags": self._tags.copy(),
+            "is_pinned": self._is_pinned,
+            "is_archived": self._is_archived,
+            "word_count": self.word_count,
+            "char_count": self.char_count,
+            "sentence_count": self.sentence_count,
+            "reading_time": self.reading_time,
+            "summary": self.summary,
+            "created_at": self._created_at.isoformat(),
+            "updated_at": self._updated_at.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Note":
+        """
+        Factory constructor: create a Note from a dictionary.
+
+        Args:
+            data: Dictionary with note fields.
+
+        Returns:
+            Note: New Note instance.
+        """
+        return cls(
+            title=data.get("title", ""),
+            content=data.get("content", ""),
+            tags=data.get("tags", []),
+            is_pinned=data.get("is_pinned", False),
+            is_archived=data.get("is_archived", False),
+            note_id=data.get("note_id") or data.get("id"),
+            created_at=data.get("created_at"),
+            updated_at=data.get("updated_at"),
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"Note(title='{self._title}', "
+            f"words={self.word_count}, "
+            f"tags={self._tags}, "
+            f"pinned={self._is_pinned})"
+        )
+
+    def __eq__(self, other) -> bool:
+        if not isinstance(other, Note):
+            return False
+        return self._title == other._title and self._content == other._content
+
+    def __len__(self) -> int:
+        """Returns the word count of the note."""
+        return self.word_count

cloudnoteslib/models/note_collection.py

@@ -0,0 +1,233 @@
+"""
+cloudnoteslib.models.note_collection — NoteCollection Container.
+
+An iterable container that holds multiple Note objects and provides
+aggregate operations such as filtering, sorting, and statistics.
+
+Demonstrates:
+    - ENCAPSULATION: Internal list is private, access via methods
+    - Python magic methods: __iter__, __len__, __getitem__, __contains__
+
+Example:
+    >>> collection = NoteCollection([note1, note2, note3])
+    >>> len(collection)
+    3
+    >>> for note in collection:
+    ...     print(note.title)
+    >>> pinned = collection.get_pinned()
+    >>> tagged = collection.filter_by_tag("work")
+"""
+
+from typing import List, Optional, Iterator
+from .note import Note
+
+
+class NoteCollection:
+    """
+    Iterable container for Note objects with aggregate operations.
+
+    Provides a clean interface for common note operations such as
+    filtering by tag, searching by keyword, sorting, and computing
+    aggregate statistics over the entire collection.
+
+    This class implements Python's iterator protocol (__iter__),
+    container protocol (__len__, __contains__, __getitem__), and
+    provides domain-specific filter/sort methods.
+
+    Attributes:
+        notes (list): Internal list of Note objects (private).
+    """
+
+    def __init__(self, notes: Optional[List[Note]] = None):
+        """
+        Initialize a NoteCollection.
+
+        Args:
+            notes: Optional list of Note objects to populate the collection.
+        """
+        self._notes: List[Note] = list(notes) if notes else []
+
+    # ─── Iterator Protocol ───
+
+    def __iter__(self) -> Iterator[Note]:
+        """Iterate over all notes in the collection."""
+        return iter(self._notes)
+
+    def __len__(self) -> int:
+        """Return the number of notes in the collection."""
+        return len(self._notes)
+
+    def __getitem__(self, index: int) -> Note:
+        """Access a note by index."""
+        return self._notes[index]
+
+    def __contains__(self, note: Note) -> bool:
+        """Check if a note is in the collection."""
+        return note in self._notes
+
+    # ─── Mutation Methods ───
+
+    def add(self, note: Note) -> None:
+        """Add a note to the collection."""
+        if not isinstance(note, Note):
+            raise TypeError("Only Note objects can be added to NoteCollection.")
+        self._notes.append(note)
+
+    def remove(self, note: Note) -> bool:
+        """
+        Remove a note from the collection.
+
+        Returns:
+            True if the note was found and removed, False otherwise.
+        """
+        try:
+            self._notes.remove(note)
+            return True
+        except ValueError:
+            return False
+
+    def clear(self) -> None:
+        """Remove all notes from the collection."""
+        self._notes.clear()
+
+    # ─── Filter Methods ───
+
+    def get_pinned(self) -> "NoteCollection":
+        """Return a new NoteCollection containing only pinned notes."""
+        return NoteCollection([n for n in self._notes if n.is_pinned])
+
+    def get_archived(self) -> "NoteCollection":
+        """Return a new NoteCollection containing only archived notes."""
+        return NoteCollection([n for n in self._notes if n.is_archived])
+
+    def get_active(self) -> "NoteCollection":
+        """Return a new NoteCollection containing only non-archived notes."""
+        return NoteCollection([n for n in self._notes if not n.is_archived])
+
+    def filter_by_tag(self, tag: str) -> "NoteCollection":
+        """
+        Filter notes that contain a specific tag.
+
+        Args:
+            tag: Tag name to filter by (case-insensitive).
+
+        Returns:
+            New NoteCollection with matching notes.
+        """
+        normalized = tag.strip().lower()
+        return NoteCollection([n for n in self._notes if n.has_tag(normalized)])
+
+    def search(self, query: str) -> "NoteCollection":
+        """
+        Simple keyword search across note titles and content.
+
+        Args:
+            query: Search keyword (case-insensitive).
+
+        Returns:
+            New NoteCollection with matching notes.
+        """
+        q = query.strip().lower()
+        if not q:
+            return NoteCollection(self._notes.copy())
+        return NoteCollection([
+            n for n in self._notes
+            if q in n.title.lower() or q in n.content.lower()
+        ])
+
+    # ─── Sort Methods ───
+
+    def sort_by_date(self, newest_first: bool = True) -> "NoteCollection":
+        """Sort notes by creation date."""
+        sorted_notes = sorted(
+            self._notes,
+            key=lambda n: n.created_at,
+            reverse=newest_first,
+        )
+        return NoteCollection(sorted_notes)
+
+    def sort_by_word_count(self, descending: bool = True) -> "NoteCollection":
+        """Sort notes by word count."""
+        sorted_notes = sorted(
+            self._notes,
+            key=lambda n: n.word_count,
+            reverse=descending,
+        )
+        return NoteCollection(sorted_notes)
+
+    def sort_by_title(self, reverse: bool = False) -> "NoteCollection":
+        """Sort notes alphabetically by title."""
+        sorted_notes = sorted(
+            self._notes,
+            key=lambda n: n.title.lower(),
+            reverse=reverse,
+        )
+        return NoteCollection(sorted_notes)
+
+    # ─── Aggregate Properties ───
+
+    @property
+    def total_words(self) -> int:
+        """Total word count across all notes."""
+        return sum(n.word_count for n in self._notes)
+
+    @property
+    def total_reading_time(self) -> float:
+        """Total estimated reading time across all notes (minutes)."""
+        return round(sum(n.reading_time for n in self._notes), 1)
+
+    @property
+    def average_word_count(self) -> float:
+        """Average word count per note."""
+        if not self._notes:
+            return 0.0
+        return round(self.total_words / len(self._notes), 1)
+
+    @property
+    def all_tags(self) -> List[str]:
+        """Unique list of all tags across all notes."""
+        tags = set()
+        for note in self._notes:
+            tags.update(note.tags)
+        return sorted(tags)
+
+    @property
+    def tag_counts(self) -> dict:
+        """Count of notes per tag."""
+        counts = {}
+        for note in self._notes:
+            for tag in note.tags:
+                counts[tag] = counts.get(tag, 0) + 1
+        return dict(sorted(counts.items(), key=lambda x: x[1], reverse=True))
+
+    @property
+    def longest_note(self) -> Optional[Note]:
+        """The note with the most words. None if collection is empty."""
+        if not self._notes:
+            return None
+        return max(self._notes, key=lambda n: n.word_count)
+
+    @property
+    def shortest_note(self) -> Optional[Note]:
+        """The note with the fewest words. None if collection is empty."""
+        if not self._notes:
+            return None
+        return min(self._notes, key=lambda n: n.word_count)
+
+    @property
+    def most_recent(self) -> Optional[Note]:
+        """The most recently created note. None if collection is empty."""
+        if not self._notes:
+            return None
+        return max(self._notes, key=lambda n: n.created_at)
+
+    def to_list(self) -> List[dict]:
+        """Serialize all notes to a list of dictionaries."""
+        return [n.to_dict() for n in self._notes]
+
+    def __repr__(self) -> str:
+        return (
+            f"NoteCollection(count={len(self._notes)}, "
+            f"total_words={self.total_words}, "
+            f"tags={self.all_tags})"
+        )