cloudnoteslib 0.1.0__py3-none-any.whl

cloudnoteslib/models/tag.py

@@ -0,0 +1,129 @@
+"""
+cloudnoteslib.models.tag — Tag Data Model.
+
+A lightweight model representing a categorization tag. Tags are normalized
+to lowercase and stripped of whitespace to ensure consistent matching.
+
+Demonstrates ENCAPSULATION through private attributes with controlled access.
+
+Example:
+    >>> tag = Tag("Work")
+    >>> tag.name
+    'work'
+    >>> tag.to_dict()
+    {'tag_id': None, 'name': 'work', 'color': '#6366f1'}
+"""
+
+from typing import Optional
+
+
+class Tag:
+    """
+    Represents a categorization tag for notes.
+
+    Tags are normalized (lowercased, stripped) on creation to ensure
+    consistent matching across the system. Each tag can optionally
+    have a color hex code for UI rendering.
+
+    Attributes:
+        name (str): Normalized tag name (lowercase).
+        color (str): Hex color code for UI display.
+        tag_id (int, optional): Database identifier.
+    """
+
+    # Default color palette for auto-assignment
+    DEFAULT_COLORS = [
+        "#6366f1",  # Indigo
+        "#8b5cf6",  # Violet
+        "#ec4899",  # Pink
+        "#f43f5e",  # Rose
+        "#f97316",  # Orange
+        "#eab308",  # Yellow
+        "#22c55e",  # Green
+        "#06b6d4",  # Cyan
+        "#3b82f6",  # Blue
+        "#a855f7",  # Purple
+    ]
+
+    def __init__(
+        self,
+        name: str,
+        color: Optional[str] = None,
+        tag_id: Optional[int] = None,
+    ):
+        """
+        Initialize a Tag.
+
+        Args:
+            name: Tag name (will be normalized to lowercase).
+            color: Optional hex color code. Auto-assigned if None.
+            tag_id: Optional database identifier.
+
+        Raises:
+            ValueError: If name is empty after stripping.
+        """
+        normalized = name.strip().lower()
+        if not normalized:
+            raise ValueError("Tag name cannot be empty.")
+
+        self._tag_id = tag_id
+        self._name = normalized
+        # Auto-assign color based on name hash if not provided
+        self._color = color or self._auto_color()
+
+    def _auto_color(self) -> str:
+        """Deterministically assign a color based on the tag name hash."""
+        index = hash(self._name) % len(self.DEFAULT_COLORS)
+        return self.DEFAULT_COLORS[index]
+
+    @property
+    def tag_id(self) -> Optional[int]:
+        """Database identifier. Read-only."""
+        return self._tag_id
+
+    @property
+    def name(self) -> str:
+        """Normalized tag name (always lowercase)."""
+        return self._name
+
+    @property
+    def color(self) -> str:
+        """Hex color code for UI rendering."""
+        return self._color
+
+    @color.setter
+    def color(self, value: str):
+        """Set tag color with basic hex validation."""
+        if not value.startswith("#") or len(value) not in (4, 7):
+            raise ValueError(f"Invalid hex color: {value}")
+        self._color = value
+
+    def to_dict(self) -> dict:
+        """Serialize tag to dictionary."""
+        return {
+            "tag_id": self._tag_id,
+            "name": self._name,
+            "color": self._color,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Tag":
+        """Create a Tag from a dictionary."""
+        return cls(
+            name=data.get("name", ""),
+            color=data.get("color"),
+            tag_id=data.get("tag_id") or data.get("id"),
+        )
+
+    def __repr__(self) -> str:
+        return f"Tag(name='{self._name}', color='{self._color}')"
+
+    def __eq__(self, other) -> bool:
+        if isinstance(other, Tag):
+            return self._name == other._name
+        if isinstance(other, str):
+            return self._name == other.strip().lower()
+        return False
+
+    def __hash__(self) -> int:
+        return hash(self._name)

cloudnoteslib/processors/__init__.py

@@ -0,0 +1,36 @@
+"""
+cloudnoteslib.processors — Note Content Processors.
+
+This package demonstrates three core OOP principles:
+
+    ABSTRACTION:
+        NoteProcessor (ABC) defines the contract that ALL processors
+        must follow. It cannot be instantiated directly.
+
+    INHERITANCE:
+        MarkdownProcessor, PlainTextProcessor, and RichTextProcessor
+        all extend NoteProcessor with their own implementations.
+
+    POLYMORPHISM:
+        All processors share the same interface (process, extract_summary,
+        get_format_type) but behave differently. The calling code doesn't
+        need to know which concrete processor is being used.
+
+Exports:
+    NoteProcessor: Abstract base class.
+    MarkdownProcessor: Handles Markdown-formatted notes.
+    PlainTextProcessor: Handles plain text notes.
+    RichTextProcessor: Handles rich/HTML text notes.
+"""
+
+from .base import NoteProcessor
+from .markdown_processor import MarkdownProcessor
+from .plaintext_processor import PlainTextProcessor
+from .richtext_processor import RichTextProcessor
+
+__all__ = [
+    "NoteProcessor",
+    "MarkdownProcessor",
+    "PlainTextProcessor",
+    "RichTextProcessor",
+]

cloudnoteslib/processors/base.py

@@ -0,0 +1,157 @@
+"""
+cloudnoteslib.processors.base — Abstract Base Class for Note Processors.
+
+Demonstrates OOP ABSTRACTION:
+    This class defines the CONTRACT that all note processors must follow.
+    It cannot be instantiated directly — only its subclasses can be used.
+    This ensures consistent behavior across all content format types.
+
+    By using ABC (Abstract Base Class), we guarantee that every processor
+    implements process(), extract_summary(), and get_format_type().
+
+Example:
+    >>> processor = NoteProcessor()  # Raises TypeError — cannot instantiate ABC
+    >>> processor = MarkdownProcessor()  # OK — concrete implementation
+"""
+
+from abc import ABC, abstractmethod
+from typing import List
+
+
+class NoteProcessor(ABC):
+    """
+    Abstract Base Class for note content processors.
+
+    OOP Principle — ABSTRACTION:
+        Defines the interface (contract) that all processors must implement.
+        Uses Python's abc.ABC and @abstractmethod to enforce this at the
+        language level. Any subclass that doesn't implement ALL abstract
+        methods will raise TypeError on instantiation.
+
+    Subclasses:
+        - MarkdownProcessor: Processes Markdown-formatted content
+        - PlainTextProcessor: Processes plain text content
+        - RichTextProcessor: Processes HTML/rich text content
+
+    Design Pattern — TEMPLATE METHOD:
+        The clean() method provides a common algorithm skeleton that
+        calls abstract methods. Subclasses override specific steps
+        while keeping the overall structure intact.
+    """
+
+    @abstractmethod
+    def process(self, content: str) -> str:
+        """
+        Process and clean the note content according to format rules.
+
+        This is the primary transformation method. Each processor
+        implements format-specific cleaning, normalization, and
+        validation logic.
+
+        Args:
+            content: Raw note content string.
+
+        Returns:
+            Processed and cleaned content string.
+        """
+        pass
+
+    @abstractmethod
+    def extract_summary(self, content: str, max_length: int = 150) -> str:
+        """
+        Extract a human-readable summary from the content.
+
+        Different formats require different summarization strategies:
+        - Markdown: strip headers/formatting before extracting
+        - Plain text: take first N characters
+        - Rich text: strip HTML tags before extracting
+
+        Args:
+            content: Full note content.
+            max_length: Maximum characters for the summary.
+
+        Returns:
+            A clean, readable summary string.
+        """
+        pass
+
+    @abstractmethod
+    def get_format_type(self) -> str:
+        """
+        Return the format identifier string for this processor.
+
+        Returns:
+            Format type string (e.g., 'markdown', 'plaintext', 'richtext').
+        """
+        pass
+
+    @abstractmethod
+    def extract_headings(self, content: str) -> List[str]:
+        """
+        Extract structural headings/sections from the content.
+
+        Args:
+            content: Full note content.
+
+        Returns:
+            List of heading strings found in the content.
+        """
+        pass
+
+    # ─── Template Method (shared algorithm skeleton) ───
+
+    def clean(self, content: str) -> str:
+        """
+        Template Method: standardized cleaning pipeline.
+
+        Applies common cleaning steps that all formats share:
+        1. Strip leading/trailing whitespace
+        2. Normalize line endings
+        3. Apply format-specific processing (delegated to subclass)
+
+        This demonstrates the TEMPLATE METHOD pattern where the
+        base class defines the algorithm structure, and subclasses
+        override specific steps.
+
+        Args:
+            content: Raw note content.
+
+        Returns:
+            Fully cleaned and processed content.
+        """
+        # Step 1: Common normalization (shared by all formats)
+        content = content.strip()
+        content = content.replace("\r\n", "\n")  # Normalize line endings
+        content = content.replace("\r", "\n")
+
+        # Step 2: Format-specific processing (delegated to subclass)
+        content = self.process(content)
+
+        return content
+
+    def get_word_count(self, content: str) -> int:
+        """
+        Count words in content after stripping format-specific markup.
+
+        This non-abstract method provides a default implementation
+        that subclasses can optionally override for format-specific
+        word counting (e.g., excluding Markdown syntax).
+
+        Args:
+            content: Note content string.
+
+        Returns:
+            Integer word count.
+        """
+        cleaned = self.process(content)
+        if not cleaned.strip():
+            return 0
+        return len(cleaned.split())
+
+    @property
+    def processor_name(self) -> str:
+        """Human-readable name of this processor."""
+        return f"{self.get_format_type().capitalize()} Processor"
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(format='{self.get_format_type()}')"

cloudnoteslib/processors/markdown_processor.py

@@ -0,0 +1,157 @@
+"""
+cloudnoteslib.processors.markdown_processor — Markdown Content Processor.
+
+Demonstrates OOP INHERITANCE and POLYMORPHISM:
+    - INHERITANCE: Extends NoteProcessor (ABC) and implements all abstract methods
+    - POLYMORPHISM: process(), extract_summary(), get_format_type() behave
+      differently from PlainTextProcessor and RichTextProcessor, but share
+      the same interface — calling code doesn't need to know which processor
+      is being used.
+
+Example:
+    >>> processor = MarkdownProcessor()
+    >>> processor.get_format_type()
+    'markdown'
+    >>> processor.process("# Hello\\n**Bold** text")
+    'Hello Bold text'
+    >>> processor.extract_headings("# Title\\n## Section\\nContent")
+    ['Title', 'Section']
+"""
+
+import re
+from typing import List
+from .base import NoteProcessor
+
+
+class MarkdownProcessor(NoteProcessor):
+    """
+    Processes Markdown-formatted note content.
+
+    Inherits from NoteProcessor and provides Markdown-specific
+    implementations for content processing, summary extraction,
+    and heading detection.
+
+    OOP Principles:
+        - INHERITANCE: Extends NoteProcessor abstract base class
+        - POLYMORPHISM: Same interface as PlainTextProcessor/RichTextProcessor
+          but with Markdown-specific behavior
+    """
+
+    def process(self, content: str) -> str:
+        """
+        Strip Markdown formatting to produce clean plain text.
+
+        Removes headers (#), bold (**), italic (*), links, images,
+        code blocks, and other Markdown syntax while preserving
+        the actual text content.
+
+        Args:
+            content: Raw Markdown content.
+
+        Returns:
+            Clean plain text with Markdown syntax removed.
+        """
+        if not content:
+            return ""
+
+        text = content
+
+        # Remove code blocks (``` ... ```)
+        text = re.sub(r'```[\s\S]*?```', '', text)
+
+        # Remove inline code (`...`)
+        text = re.sub(r'`([^`]+)`', r'\1', text)
+
+        # Remove images ![alt](url)
+        text = re.sub(r'!\[([^\]]*)\]\([^)]+\)', r'\1', text)
+
+        # Remove links [text](url) → keep text
+        text = re.sub(r'\[([^\]]+)\]\([^)]+\)', r'\1', text)
+
+        # Remove headers (# ## ### etc.) → keep text
+        text = re.sub(r'^#{1,6}\s+', '', text, flags=re.MULTILINE)
+
+        # Remove bold (**text** or __text__) → keep text
+        text = re.sub(r'\*\*(.+?)\*\*', r'\1', text)
+        text = re.sub(r'__(.+?)__', r'\1', text)
+
+        # Remove italic (*text* or _text_) → keep text
+        text = re.sub(r'\*(.+?)\*', r'\1', text)
+        text = re.sub(r'_(.+?)_', r'\1', text)
+
+        # Remove strikethrough (~~text~~) → keep text
+        text = re.sub(r'~~(.+?)~~', r'\1', text)
+
+        # Remove blockquotes (> ...) → keep text
+        text = re.sub(r'^>\s+', '', text, flags=re.MULTILINE)
+
+        # Remove horizontal rules (--- or ***)
+        text = re.sub(r'^[-*]{3,}\s*$', '', text, flags=re.MULTILINE)
+
+        # Remove list markers (- or * or 1.)
+        text = re.sub(r'^\s*[-*+]\s+', '', text, flags=re.MULTILINE)
+        text = re.sub(r'^\s*\d+\.\s+', '', text, flags=re.MULTILINE)
+
+        # Collapse multiple blank lines
+        text = re.sub(r'\n{3,}', '\n\n', text)
+
+        return text.strip()
+
+    def extract_summary(self, content: str, max_length: int = 150) -> str:
+        """
+        Extract a summary by stripping Markdown and taking first N chars.
+
+        Args:
+            content: Full Markdown content.
+            max_length: Maximum characters in summary.
+
+        Returns:
+            Clean text summary without Markdown formatting.
+        """
+        clean = self.process(content)
+        if len(clean) <= max_length:
+            return clean
+        # Cut at word boundary
+        truncated = clean[:max_length]
+        last_space = truncated.rfind(" ")
+        if last_space > 0:
+            truncated = truncated[:last_space]
+        return truncated + "..."
+
+    def get_format_type(self) -> str:
+        """Return the format identifier."""
+        return "markdown"
+
+    def extract_headings(self, content: str) -> List[str]:
+        """
+        Extract Markdown headings (lines starting with #).
+
+        Args:
+            content: Full Markdown content.
+
+        Returns:
+            List of heading text strings (without # symbols).
+        """
+        headings = []
+        for line in content.split("\n"):
+            match = re.match(r'^(#{1,6})\s+(.+)', line.strip())
+            if match:
+                headings.append(match.group(2).strip())
+        return headings
+
+    def get_heading_structure(self, content: str) -> List[dict]:
+        """
+        Extract headings with their hierarchy level.
+
+        Returns:
+            List of dicts: [{'level': 1, 'text': 'Title'}, ...]
+        """
+        structure = []
+        for line in content.split("\n"):
+            match = re.match(r'^(#{1,6})\s+(.+)', line.strip())
+            if match:
+                structure.append({
+                    "level": len(match.group(1)),
+                    "text": match.group(2).strip(),
+                })
+        return structure

cloudnoteslib/processors/plaintext_processor.py

@@ -0,0 +1,103 @@
+"""
+cloudnoteslib.processors.plaintext_processor — Plain Text Processor.
+
+INHERITANCE: Extends NoteProcessor with plain-text-specific logic.
+POLYMORPHISM: Same interface as MarkdownProcessor/RichTextProcessor.
+
+Example:
+    >>> processor = PlainTextProcessor()
+    >>> processor.get_format_type()
+    'plaintext'
+    >>> processor.process("  Hello   World  ")
+    'Hello World'
+"""
+
+import re
+from typing import List
+from .base import NoteProcessor
+
+
+class PlainTextProcessor(NoteProcessor):
+    """
+    Processes plain text note content.
+
+    Provides minimal processing: whitespace normalization, line
+    cleanup, and basic structural extraction.
+    """
+
+    def process(self, content: str) -> str:
+        """
+        Normalize whitespace and clean up plain text.
+
+        Args:
+            content: Raw plain text content.
+
+        Returns:
+            Cleaned text with normalized whitespace.
+        """
+        if not content:
+            return ""
+
+        text = content
+
+        # Normalize multiple spaces to single space
+        text = re.sub(r'[ \t]+', ' ', text)
+
+        # Collapse 3+ newlines to double newline
+        text = re.sub(r'\n{3,}', '\n\n', text)
+
+        # Strip each line
+        lines = [line.strip() for line in text.split('\n')]
+        text = '\n'.join(lines)
+
+        return text.strip()
+
+    def extract_summary(self, content: str, max_length: int = 150) -> str:
+        """
+        Extract summary from first N characters of plain text.
+
+        Args:
+            content: Full plain text content.
+            max_length: Maximum characters.
+
+        Returns:
+            First N characters, cut at word boundary.
+        """
+        clean = self.process(content)
+        if len(clean) <= max_length:
+            return clean
+        truncated = clean[:max_length]
+        last_space = truncated.rfind(" ")
+        if last_space > 0:
+            truncated = truncated[:last_space]
+        return truncated + "..."
+
+    def get_format_type(self) -> str:
+        return "plaintext"
+
+    def extract_headings(self, content: str) -> List[str]:
+        """
+        Infer headings from all-caps lines or lines ending with colon.
+
+        Plain text doesn't have formal heading syntax, so we use
+        heuristics: lines that are ALL CAPS or end with ':' and
+        are short enough to be titles.
+
+        Args:
+            content: Full plain text content.
+
+        Returns:
+            List of inferred heading strings.
+        """
+        headings = []
+        for line in content.split("\n"):
+            stripped = line.strip()
+            if not stripped:
+                continue
+            # All caps lines under 80 chars could be headings
+            if stripped.isupper() and len(stripped) < 80:
+                headings.append(stripped.title())
+            # Short lines ending with colon
+            elif stripped.endswith(":") and len(stripped) < 60:
+                headings.append(stripped[:-1].strip())
+        return headings

cloudnoteslib/processors/richtext_processor.py

@@ -0,0 +1,122 @@
+"""
+cloudnoteslib.processors.richtext_processor — Rich/HTML Text Processor.
+
+INHERITANCE: Third concrete subclass of NoteProcessor.
+POLYMORPHISM: Same interface, different behavior — strips HTML tags.
+
+Example:
+    >>> processor = RichTextProcessor()
+    >>> processor.process("<h1>Title</h1><p><b>Bold</b> text</p>")
+    'Title Bold text'
+"""
+
+import re
+from typing import List
+from .base import NoteProcessor
+
+
+class RichTextProcessor(NoteProcessor):
+    """
+    Processes HTML/rich text note content.
+
+    Strips HTML tags while preserving text content. Handles common
+    HTML entities and structural elements.
+    """
+
+    def process(self, content: str) -> str:
+        """
+        Strip HTML tags and entities to extract plain text.
+
+        Args:
+            content: Raw HTML/rich text content.
+
+        Returns:
+            Clean text with all HTML markup removed.
+        """
+        if not content:
+            return ""
+
+        text = content
+
+        # Replace common block-level elements with newlines
+        text = re.sub(r'<br\s*/?>', '\n', text, flags=re.IGNORECASE)
+        text = re.sub(r'</p>', '\n', text, flags=re.IGNORECASE)
+        text = re.sub(r'</div>', '\n', text, flags=re.IGNORECASE)
+        text = re.sub(r'</li>', '\n', text, flags=re.IGNORECASE)
+        text = re.sub(r'</h[1-6]>', '\n', text, flags=re.IGNORECASE)
+
+        # Remove all remaining HTML tags
+        text = re.sub(r'<[^>]+>', '', text)
+
+        # Decode common HTML entities
+        html_entities = {
+            '&amp;': '&',
+            '&lt;': '<',
+            '&gt;': '>',
+            '&quot;': '"',
+            '&#39;': "'",
+            '&nbsp;': ' ',
+            '&mdash;': '—',
+            '&ndash;': '–',
+            '&hellip;': '...',
+        }
+        for entity, char in html_entities.items():
+            text = text.replace(entity, char)
+
+        # Remove numeric HTML entities
+        text = re.sub(r'&#\d+;', '', text)
+
+        # Normalize whitespace
+        text = re.sub(r'[ \t]+', ' ', text)
+        text = re.sub(r'\n{3,}', '\n\n', text)
+
+        lines = [line.strip() for line in text.split('\n')]
+        text = '\n'.join(lines)
+
+        return text.strip()
+
+    def extract_summary(self, content: str, max_length: int = 150) -> str:
+        """
+        Extract summary by stripping HTML first, then truncating.
+
+        Args:
+            content: Full HTML content.
+            max_length: Maximum characters.
+
+        Returns:
+            Clean text summary without HTML tags.
+        """
+        clean = self.process(content)
+        if len(clean) <= max_length:
+            return clean
+        truncated = clean[:max_length]
+        last_space = truncated.rfind(" ")
+        if last_space > 0:
+            truncated = truncated[:last_space]
+        return truncated + "..."
+
+    def get_format_type(self) -> str:
+        return "richtext"
+
+    def extract_headings(self, content: str) -> List[str]:
+        """
+        Extract headings from HTML heading tags (h1-h6).
+
+        Args:
+            content: Full HTML content.
+
+        Returns:
+            List of heading text strings.
+        """
+        headings = []
+        matches = re.findall(
+            r'<h[1-6][^>]*>(.*?)</h[1-6]>',
+            content,
+            flags=re.IGNORECASE | re.DOTALL,
+        )
+        for match in matches:
+            # Strip any nested tags inside the heading
+            clean = re.sub(r'<[^>]+>', '', match).strip()
+            if clean:
+                headings.append(clean)
+        return headings