notesctl 1.0.0__py3-none-any.whl

notesctl/database/models.py

@@ -0,0 +1,74 @@
+"""Data models for Apple Notes database entities."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+
+@dataclass
+class Attachment:
+    """Represents a media attachment in a note."""
+
+    identifier: str
+    filename: str | None
+    mime_type: str | None
+    media_path: Path | None
+    note_id: int
+
+    @property
+    def is_image(self) -> bool:
+        """Check if attachment is an image."""
+        if self.mime_type:
+            # Handle both MIME types and UTIs
+            # UTIs: public.jpeg, public.png, public.heic, public.image, etc.
+            # MIME: image/jpeg, image/png, etc.
+            uti_lower = self.mime_type.lower()
+            if uti_lower.startswith("image/"):
+                return True
+            if uti_lower.startswith("public."):
+                image_utis = {"jpeg", "png", "gif", "heic", "heif", "tiff", "bmp", "image"}
+                uti_type = uti_lower.replace("public.", "")
+                return uti_type in image_utis
+        if self.filename:
+            return self.filename.lower().endswith((".jpg", ".jpeg", ".png", ".gif", ".heic"))
+        return False
+
+
+@dataclass
+class Folder:
+    """Represents a Notes folder."""
+
+    id: int
+    name: str
+    parent_id: int | None = None
+    identifier: str | None = None
+
+
+@dataclass
+class Note:
+    """Represents an Apple Note with its content and metadata."""
+
+    id: int
+    title: str
+    created: datetime
+    modified: datetime
+    folder: str
+    folder_id: int | None = None
+    content_data: bytes | None = None
+    is_encrypted: bool = False
+    is_pinned: bool = False
+    is_trashed: bool = False
+    identifier: str | None = None
+    attachments: list[Attachment] = field(default_factory=list)
+
+    @property
+    def safe_filename(self) -> str:
+        """Generate a safe filename from the note title."""
+        # Remove or replace characters that are problematic in filenames
+        unsafe_chars = '<>:"/\\|?*'
+        safe_title = self.title
+        for char in unsafe_chars:
+            safe_title = safe_title.replace(char, "_")
+        # Limit length and strip whitespace
+        safe_title = safe_title.strip()[:100]
+        return safe_title or "untitled"

notesctl/database/queries.py

@@ -0,0 +1,241 @@
+"""SQL queries for reading Apple Notes data (SELECT only)."""
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+from .connection import SafeNotesDatabase
+from .models import Attachment, Folder, Note
+
+# Apple's Core Data timestamp epoch (2001-01-01 00:00:00 UTC)
+APPLE_EPOCH = datetime(2001, 1, 1, tzinfo=UTC)
+
+
+def apple_timestamp_to_datetime(timestamp: float | None) -> datetime:
+    """Convert Apple Core Data timestamp to Python datetime."""
+    if timestamp is None:
+        return datetime.now(tz=UTC)
+    # Apple timestamps are seconds since 2001-01-01
+    return datetime.fromtimestamp(timestamp + APPLE_EPOCH.timestamp(), tz=UTC)
+
+
+class NotesQueries:
+    """Query class for extracting notes data from Apple Notes database."""
+
+    # Path to media attachments relative to Notes container
+    MEDIA_BASE = Path.home() / "Library/Group Containers/group.com.apple.notes"
+
+    def __init__(self, db: SafeNotesDatabase):
+        """Initialize with database connection."""
+        self.db = db
+
+    def get_folders(self) -> list[Folder]:
+        """
+        Get all non-system folders.
+
+        Returns:
+            List of Folder objects
+        """
+        query = """
+        SELECT
+            Z_PK as id,
+            ZTITLE2 as name,
+            ZPARENT as parent_id,
+            ZIDENTIFIER as identifier
+        FROM ZICCLOUDSYNCINGOBJECT
+        WHERE ZTITLE2 IS NOT NULL
+          AND ZMARKEDFORDELETION != 1
+        ORDER BY ZTITLE2
+        """
+        rows = self.db.fetchall(query)
+        return [
+            Folder(
+                id=row["id"],
+                name=row["name"],
+                parent_id=row["parent_id"],
+                identifier=row["identifier"],
+            )
+            for row in rows
+        ]
+
+    def get_folder_by_name(self, name: str) -> Folder | None:
+        """Get a folder by its name."""
+        query = """
+        SELECT
+            Z_PK as id,
+            ZTITLE2 as name,
+            ZPARENT as parent_id,
+            ZIDENTIFIER as identifier
+        FROM ZICCLOUDSYNCINGOBJECT
+        WHERE ZTITLE2 = ?
+          AND ZMARKEDFORDELETION != 1
+        LIMIT 1
+        """
+        row = self.db.fetchone(query, (name,))
+        if row:
+            return Folder(
+                id=row["id"],
+                name=row["name"],
+                parent_id=row["parent_id"],
+                identifier=row["identifier"],
+            )
+        return None
+
+    def get_notes(
+        self,
+        folder_id: int | None = None,
+        include_trashed: bool = False,
+    ) -> list[Note]:
+        """
+        Get all notes, optionally filtered by folder.
+
+        Args:
+            folder_id: Optional folder ID to filter by
+            include_trashed: Whether to include trashed notes
+
+        Returns:
+            List of Note objects with basic metadata (content loaded separately)
+        """
+        query = """
+        SELECT
+            n.Z_PK as id,
+            n.ZTITLE1 as title,
+            n.ZCREATIONDATE3 as created,
+            n.ZMODIFICATIONDATE1 as modified,
+            n.ZFOLDER as folder_id,
+            n.ZIDENTIFIER as identifier,
+            n.ZISPASSWORDPROTECTED as is_encrypted,
+            n.ZISPINNED as is_pinned,
+            n.ZMARKEDFORDELETION as is_trashed,
+            f.ZTITLE2 as folder_name,
+            d.ZDATA as content_data
+        FROM ZICCLOUDSYNCINGOBJECT n
+        LEFT JOIN ZICCLOUDSYNCINGOBJECT f ON n.ZFOLDER = f.Z_PK
+        LEFT JOIN ZICNOTEDATA d ON n.ZNOTEDATA = d.Z_PK
+        WHERE n.ZTITLE1 IS NOT NULL
+        """
+
+        params: list = []
+
+        if folder_id is not None:
+            query += " AND n.ZFOLDER = ?"
+            params.append(folder_id)
+
+        if not include_trashed:
+            query += " AND (n.ZMARKEDFORDELETION IS NULL OR n.ZMARKEDFORDELETION != 1)"
+
+        query += " ORDER BY n.ZMODIFICATIONDATE1 DESC"
+
+        rows = self.db.fetchall(query, tuple(params))
+
+        notes = []
+        for row in rows:
+            note = Note(
+                id=row["id"],
+                title=row["title"] or "Untitled",
+                created=apple_timestamp_to_datetime(row["created"]),
+                modified=apple_timestamp_to_datetime(row["modified"]),
+                folder=row["folder_name"] or "Notes",
+                folder_id=row["folder_id"],
+                content_data=row["content_data"],
+                is_encrypted=bool(row["is_encrypted"]),
+                is_pinned=bool(row["is_pinned"]),
+                is_trashed=bool(row["is_trashed"]),
+                identifier=row["identifier"],
+            )
+            notes.append(note)
+
+        return notes
+
+    def get_note_attachments(self, note_id: int) -> list[Attachment]:
+        """
+        Get attachments for a specific note.
+
+        Args:
+            note_id: The note's primary key
+
+        Returns:
+            List of Attachment objects
+        """
+        query = """
+        SELECT
+            a.Z_PK as id,
+            a.ZIDENTIFIER as identifier,
+            a.ZFILENAME as filename,
+            a.ZTYPEUTI as type_uti,
+            a.ZMEDIA as media_id,
+            m.ZFILENAME as media_filename,
+            m.ZIDENTIFIER as media_identifier
+        FROM ZICCLOUDSYNCINGOBJECT a
+        LEFT JOIN ZICCLOUDSYNCINGOBJECT m ON a.ZMEDIA = m.Z_PK
+        WHERE a.ZNOTE = ?
+          AND a.ZTYPEUTI IS NOT NULL
+        """
+        rows = self.db.fetchall(query, (note_id,))
+
+        attachments = []
+        for row in rows:
+            # Try to find the media file path
+            media_path = None
+            if row["media_identifier"]:
+                # Look in the Media folder structure
+                media_path = self._find_media_file(row["media_identifier"])
+
+            attachment = Attachment(
+                identifier=row["identifier"] or str(row["id"]),
+                filename=row["filename"] or row["media_filename"],
+                mime_type=row["type_uti"],  # ZTYPEUTI stores the UTI (e.g., public.jpeg)
+                media_path=media_path,
+                note_id=note_id,
+            )
+            attachments.append(attachment)
+
+        return attachments
+
+    def _find_media_file(self, identifier: str) -> Path | None:
+        """
+        Find the actual media file on disk.
+
+        Args:
+            identifier: The media identifier
+
+        Returns:
+            Path to the media file if found
+        """
+        # Media files are stored in Accounts/<UUID>/Media/<identifier>/
+        accounts_path = self.MEDIA_BASE / "Accounts"
+        if not accounts_path.exists():
+            return None
+
+        for account_dir in accounts_path.iterdir():
+            if not account_dir.is_dir():
+                continue
+            media_dir = account_dir / "Media" / identifier
+            if media_dir.exists():
+                # Return the first file found in the directory
+                for file in media_dir.iterdir():
+                    if file.is_file() and not file.name.startswith("."):
+                        return file
+        return None
+
+    def get_note_count(self) -> int:
+        """Get total number of non-trashed notes."""
+        query = """
+        SELECT COUNT(*) as count
+        FROM ZICCLOUDSYNCINGOBJECT
+        WHERE ZTITLE1 IS NOT NULL
+          AND (ZMARKEDFORDELETION IS NULL OR ZMARKEDFORDELETION != 1)
+        """
+        row = self.db.fetchone(query)
+        return row["count"] if row else 0
+
+    def get_encrypted_note_count(self) -> int:
+        """Get number of encrypted notes."""
+        query = """
+        SELECT COUNT(*) as count
+        FROM ZICCLOUDSYNCINGOBJECT
+        WHERE ZTITLE1 IS NOT NULL
+          AND ZISPASSWORDPROTECTED = 1
+          AND (ZMARKEDFORDELETION IS NULL OR ZMARKEDFORDELETION != 1)
+        """
+        row = self.db.fetchone(query)
+        return row["count"] if row else 0

notesctl/exporter.py

@@ -0,0 +1,245 @@
+"""Note exporter that orchestrates the export process."""
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from rich.console import Console
+from rich.progress import Progress, TaskID
+
+from .converter.markdown import MarkdownConverter, MarkdownOptions
+from .database import Note, NotesQueries, SafeNotesDatabase
+from .parser import NoteParser, ParsedNote
+
+console = Console()
+
+
+@dataclass
+class ExportResult:
+    """Result of an export operation."""
+
+    total_notes: int
+    exported_notes: int
+    skipped_encrypted: int
+    skipped_errors: int
+    attachments_copied: int
+    output_path: Path
+    exported_files: list[Path]
+    errors: list[str]
+
+
+@dataclass
+class ExportOptions:
+    """Options for export operation."""
+
+    output_dir: Path
+    folder_name: str | None = None
+    include_trashed: bool = False
+    include_frontmatter: bool = True
+    dry_run: bool = False
+    organize_by_folder: bool = True
+
+
+class NotesExporter:
+    """Exports Apple Notes to Markdown files."""
+
+    def __init__(self, db_path: Path | None = None):
+        """Initialize exporter with optional custom database path."""
+        self.db_path = db_path
+        self.parser = NoteParser()
+
+    def export(
+        self,
+        options: ExportOptions,
+        progress: Progress | None = None,
+    ) -> ExportResult:
+        """
+        Export notes to Markdown files.
+
+        Args:
+            options: Export options
+            progress: Optional Rich progress bar
+
+        Returns:
+            ExportResult with statistics
+        """
+        result = ExportResult(
+            total_notes=0,
+            exported_notes=0,
+            skipped_encrypted=0,
+            skipped_errors=0,
+            attachments_copied=0,
+            output_path=options.output_dir,
+            exported_files=[],
+            errors=[],
+        )
+
+        with SafeNotesDatabase(self.db_path) as db:
+            queries = NotesQueries(db)
+
+            # Get folder filter if specified
+            folder_id = None
+            if options.folder_name:
+                folder = queries.get_folder_by_name(options.folder_name)
+                if folder:
+                    folder_id = folder.id
+                else:
+                    result.errors.append(f"Folder '{options.folder_name}' not found")
+                    return result
+
+            # Get notes
+            notes = queries.get_notes(
+                folder_id=folder_id,
+                include_trashed=options.include_trashed,
+            )
+            result.total_notes = len(notes)
+
+            if not notes:
+                return result
+
+            # Create output directory (unless dry run)
+            if not options.dry_run:
+                options.output_dir.mkdir(parents=True, exist_ok=True)
+
+            # Set up progress tracking
+            task: TaskID | None = None
+            if progress:
+                task = progress.add_task("Exporting notes...", total=len(notes))
+
+            # Export each note
+            converter = MarkdownConverter(
+                MarkdownOptions(include_frontmatter=options.include_frontmatter)
+            )
+
+            for note in notes:
+                try:
+                    self._export_note(
+                        note=note,
+                        queries=queries,
+                        converter=converter,
+                        options=options,
+                        result=result,
+                    )
+                except Exception as e:
+                    result.skipped_errors += 1
+                    result.errors.append(f"Error exporting '{note.title}': {e}")
+
+                if progress and task is not None:
+                    progress.update(task, advance=1)
+
+        return result
+
+    def _export_note(
+        self,
+        note: Note,
+        queries: NotesQueries,
+        converter: MarkdownConverter,
+        options: ExportOptions,
+        result: ExportResult,
+    ) -> None:
+        """Export a single note."""
+        # Skip encrypted notes
+        if note.is_encrypted:
+            result.skipped_encrypted += 1
+            return
+
+        # Parse note content
+        parsed: ParsedNote
+        if note.content_data:
+            parsed = self.parser.parse(note.content_data, note.title)
+        else:
+            parsed = ParsedNote(title=note.title)
+
+        # Get attachments
+        attachments = queries.get_note_attachments(note.id)
+        note.attachments = attachments
+
+        # Convert to Markdown
+        markdown = converter.convert(note, parsed, attachments)
+
+        # Determine output path
+        if options.organize_by_folder:
+            folder_dir = options.output_dir / self._safe_folder_name(note.folder)
+        else:
+            folder_dir = options.output_dir
+
+        filename = f"{note.safe_filename}.md"
+        output_file = folder_dir / filename
+
+        # Handle duplicate filenames
+        counter = 1
+        while output_file.exists():
+            output_file = folder_dir / f"{note.safe_filename}_{counter}.md"
+            counter += 1
+
+        if options.dry_run:
+            result.exported_files.append(output_file)
+            result.exported_notes += 1
+            return
+
+        # Create folder and write file
+        folder_dir.mkdir(parents=True, exist_ok=True)
+        output_file.write_text(markdown, encoding="utf-8")
+        result.exported_files.append(output_file)
+        result.exported_notes += 1
+
+        # Copy attachments
+        for attachment in attachments:
+            if attachment.media_path and attachment.media_path.exists():
+                att_dir = folder_dir / "attachments" / attachment.identifier
+                att_dir.mkdir(parents=True, exist_ok=True)
+                dest = att_dir / (attachment.filename or attachment.media_path.name)
+                if not dest.exists():
+                    shutil.copy2(attachment.media_path, dest)
+                    result.attachments_copied += 1
+
+    def _safe_folder_name(self, name: str) -> str:
+        """Create a safe folder name."""
+        unsafe_chars = '<>:"/\\|?*'
+        safe_name = name
+        for char in unsafe_chars:
+            safe_name = safe_name.replace(char, "_")
+        return safe_name.strip() or "Notes"
+
+    def list_notes(
+        self,
+        folder_name: str | None = None,
+        include_trashed: bool = False,
+    ) -> list[Note]:
+        """List notes with optional folder filter."""
+        with SafeNotesDatabase(self.db_path) as db:
+            queries = NotesQueries(db)
+
+            folder_id = None
+            if folder_name:
+                folder = queries.get_folder_by_name(folder_name)
+                if folder:
+                    folder_id = folder.id
+
+            return queries.get_notes(
+                folder_id=folder_id,
+                include_trashed=include_trashed,
+            )
+
+    def list_folders(self) -> list[tuple[str, int]]:
+        """List all folders with note counts."""
+        with SafeNotesDatabase(self.db_path) as db:
+            queries = NotesQueries(db)
+            folders = queries.get_folders()
+
+            # Count notes per folder
+            folder_counts: dict[str, int] = {}
+            notes = queries.get_notes()
+            for note in notes:
+                folder_counts[note.folder] = folder_counts.get(note.folder, 0) + 1
+
+            return [(f.name, folder_counts.get(f.name, 0)) for f in folders]
+
+    def get_stats(self) -> dict[str, int]:
+        """Get database statistics."""
+        with SafeNotesDatabase(self.db_path) as db:
+            queries = NotesQueries(db)
+            return {
+                "total_notes": queries.get_note_count(),
+                "encrypted_notes": queries.get_encrypted_note_count(),
+            }

notesctl/parser/__init__.py

@@ -0,0 +1,5 @@
+"""Parser for Apple Notes content."""
+
+from .note_parser import NoteParser, ParsedNote
+
+__all__ = ["NoteParser", "ParsedNote"]