notesctl 1.0.0__py3-none-any.whl

notesctl/parser/note_parser.py

@@ -0,0 +1,227 @@
+"""Parser for Apple Notes gzip-compressed protobuf content."""
+
+import gzip
+from dataclasses import dataclass, field
+from enum import IntEnum
+
+from .protobuf.notestore_pb2 import NoteStoreProto
+
+
+class StyleType(IntEnum):
+    """Paragraph style types in Apple Notes."""
+
+    TITLE = 0
+    HEADING = 1
+    SUBHEADING = 2
+    MONOSPACED = 4
+    DOTTED_LIST = 100  # Bullet list
+    DASHED_LIST = 101
+    NUMBERED_LIST = 102
+    CHECKLIST = 103
+
+
+@dataclass
+class TextRun:
+    """A run of text with consistent formatting."""
+
+    text: str
+    bold: bool = False
+    italic: bool = False
+    underline: bool = False
+    strikethrough: bool = False
+    monospace: bool = False
+    link: str | None = None
+    attachment_id: str | None = None
+
+
+@dataclass
+class Paragraph:
+    """A paragraph with its style and text runs."""
+
+    runs: list[TextRun] = field(default_factory=list)
+    style: StyleType | None = None
+    indent: int = 0
+    is_checklist: bool = False
+    checklist_checked: bool = False
+    is_blockquote: bool = False
+    list_item_number: int | None = None  # For numbered lists
+
+    @property
+    def plain_text(self) -> str:
+        """Get plain text content without formatting."""
+        return "".join(run.text for run in self.runs)
+
+
+@dataclass
+class ParsedNote:
+    """Parsed note content ready for conversion."""
+
+    title: str
+    paragraphs: list[Paragraph] = field(default_factory=list)
+    attachment_ids: list[str] = field(default_factory=list)
+
+    @property
+    def plain_text(self) -> str:
+        """Get full plain text content."""
+        return "\n".join(p.plain_text for p in self.paragraphs)
+
+
+class NoteParser:
+    """Parser for Apple Notes protobuf content."""
+
+    def __init__(self):
+        """Initialize the parser."""
+        self._numbered_list_counters: dict[int, int] = {}
+
+    def parse(self, data: bytes, title: str = "Untitled") -> ParsedNote:
+        """
+        Parse gzip-compressed protobuf note data.
+
+        Args:
+            data: Gzip-compressed protobuf data
+            title: Note title (from database)
+
+        Returns:
+            ParsedNote with parsed content
+        """
+        if not data:
+            return ParsedNote(title=title)
+
+        # Decompress gzip data
+        try:
+            decompressed = gzip.decompress(data)
+        except gzip.BadGzipFile:
+            # Data might not be gzipped, try raw protobuf
+            decompressed = data
+
+        # Parse protobuf
+        try:
+            proto = NoteStoreProto()
+            proto.ParseFromString(decompressed)
+        except Exception:
+            # If parsing fails, return empty note
+            return ParsedNote(title=title)
+
+        return self._parse_proto(proto, title)
+
+    def _parse_proto(self, proto: NoteStoreProto, title: str) -> ParsedNote:
+        """Parse the protobuf message into structured content."""
+        note = ParsedNote(title=title)
+
+        if not proto.HasField("document") or not proto.document.HasField("note"):
+            return note
+
+        note_proto = proto.document.note
+        text = note_proto.note_text
+
+        # Reset numbered list counters for this note
+        self._numbered_list_counters = {}
+
+        # Process attribute runs
+        position = 0
+        current_paragraph = Paragraph()
+        paragraphs: list[Paragraph] = []
+
+        for attr_run in note_proto.attribute_run:
+            run_length = attr_run.length
+            run_text = text[position : position + run_length]
+            position += run_length
+
+            # Get paragraph style if present
+            style = None
+            indent = 0
+            is_checklist = False
+            checklist_checked = False
+            is_blockquote = False
+
+            if attr_run.HasField("paragraph_style"):
+                ps = attr_run.paragraph_style
+                if ps.HasField("style_type"):
+                    try:
+                        style = StyleType(ps.style_type)
+                    except ValueError:
+                        pass
+
+                if ps.HasField("indent_amount"):
+                    indent = ps.indent_amount
+
+                if ps.HasField("checklist"):
+                    is_checklist = True
+                    if ps.checklist.HasField("done"):
+                        checklist_checked = bool(ps.checklist.done)
+
+                if ps.HasField("block_quote"):
+                    is_blockquote = bool(ps.block_quote)
+
+            # Get font hints for italic detection
+            is_italic = False
+            if attr_run.HasField("font"):
+                # Font hints: 1 = italic
+                if attr_run.font.HasField("font_hints"):
+                    is_italic = (attr_run.font.font_hints & 1) != 0
+
+            # Create text run with formatting
+            text_run = TextRun(
+                text=run_text,
+                bold=attr_run.HasField("font_weight") and attr_run.font_weight > 0,
+                italic=is_italic,
+                underline=attr_run.HasField("underlined") and attr_run.underlined > 0,
+                strikethrough=attr_run.HasField("strikethrough") and attr_run.strikethrough > 0,
+                monospace=style == StyleType.MONOSPACED if style else False,
+                link=attr_run.link if attr_run.HasField("link") else None,
+            )
+
+            # Check for attachment
+            if attr_run.HasField("attachment_info"):
+                if attr_run.attachment_info.HasField("attachment_identifier"):
+                    att_id = attr_run.attachment_info.attachment_identifier
+                    text_run.attachment_id = att_id
+                    note.attachment_ids.append(att_id)
+
+            # Split by newlines to create paragraphs
+            lines = run_text.split("\n")
+            for i, line in enumerate(lines):
+                if i > 0:
+                    # New paragraph on newline
+                    if current_paragraph.runs or current_paragraph.style:
+                        paragraphs.append(current_paragraph)
+                    current_paragraph = Paragraph()
+
+                if line or i == len(lines) - 1:
+                    line_run = TextRun(
+                        text=line,
+                        bold=text_run.bold,
+                        italic=text_run.italic,
+                        underline=text_run.underline,
+                        strikethrough=text_run.strikethrough,
+                        monospace=text_run.monospace,
+                        link=text_run.link,
+                        attachment_id=text_run.attachment_id if i == 0 else None,
+                    )
+                    current_paragraph.runs.append(line_run)
+
+                # Apply paragraph style to first line of this run
+                if i == 0:
+                    if style is not None:
+                        current_paragraph.style = style
+                    current_paragraph.indent = indent
+                    current_paragraph.is_checklist = is_checklist
+                    current_paragraph.checklist_checked = checklist_checked
+                    current_paragraph.is_blockquote = is_blockquote
+
+                    # Track numbered list items
+                    if style == StyleType.NUMBERED_LIST:
+                        counter_key = indent
+                        self._numbered_list_counters[counter_key] = (
+                            self._numbered_list_counters.get(counter_key, 0) + 1
+                        )
+                        current_paragraph.list_item_number = self._numbered_list_counters[
+                            counter_key
+                        ]
+
+        # Add final paragraph
+        if current_paragraph.runs:
+            paragraphs.append(current_paragraph)
+
+        note.paragraphs = paragraphs
+        return note

notesctl/parser/protobuf/__init__.py

@@ -0,0 +1,5 @@
+"""Generated protobuf bindings for Apple Notes."""
+
+from .notestore_pb2 import NoteStoreProto
+
+__all__ = ["NoteStoreProto"]

notesctl/parser/protobuf/notestore_pb2.py

@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: notestore.proto
+# Protobuf Python Version: 6.33.4
+"""Generated protocol buffer code."""
+
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC, 6, 33, 4, "", "notestore.proto"
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(
+    b'\n\x0fnotestore.proto\x12\tnotestore"7\n\x0eNoteStoreProto\x12%\n\x08\x64ocument\x18\x02 \x02(\x0b\x32\x13.notestore.Document")\n\x08\x44ocument\x12\x1d\n\x04note\x18\x03 \x02(\x0b\x32\x0f.notestore.Note"I\n\x04Note\x12\x11\n\tnote_text\x18\x02 \x02(\t\x12.\n\rattribute_run\x18\x05 \x03(\x0b\x32\x17.notestore.AttributeRun"\xa9\x02\n\x0c\x41ttributeRun\x12\x0e\n\x06length\x18\x01 \x02(\x05\x12\x32\n\x0fparagraph_style\x18\x02 \x01(\x0b\x32\x19.notestore.ParagraphStyle\x12\x1d\n\x04\x66ont\x18\x03 \x01(\x0b\x32\x0f.notestore.Font\x12\x13\n\x0b\x66ont_weight\x18\x05 \x01(\x05\x12\x12\n\nunderlined\x18\x06 \x01(\x05\x12\x15\n\rstrikethrough\x18\x07 \x01(\x05\x12\x13\n\x0bsuperscript\x18\x08 \x01(\x05\x12\x0c\n\x04link\x18\t \x01(\t\x12\x1f\n\x05\x63olor\x18\n \x01(\x0b\x32\x10.notestore.Color\x12\x32\n\x0f\x61ttachment_info\x18\x0c \x01(\x0b\x32\x19.notestore.AttachmentInfo"\x8c\x01\n\x0eParagraphStyle\x12\x12\n\nstyle_type\x18\x01 \x01(\x05\x12\x11\n\talignment\x18\x02 \x01(\x05\x12\x15\n\rindent_amount\x18\x04 \x01(\x05\x12\'\n\tchecklist\x18\x05 \x01(\x0b\x32\x14.notestore.Checklist\x12\x13\n\x0b\x62lock_quote\x18\x06 \x01(\x05"\'\n\tChecklist\x12\x0c\n\x04uuid\x18\x01 \x01(\x0c\x12\x0c\n\x04\x64one\x18\x02 \x01(\x05"A\n\x04\x46ont\x12\x11\n\tfont_name\x18\x01 \x01(\t\x12\x12\n\npoint_size\x18\x02 \x01(\x02\x12\x12\n\nfont_hints\x18\x03 \x01(\x05"@\n\x05\x43olor\x12\x0b\n\x03red\x18\x01 \x01(\x02\x12\r\n\x05green\x18\x02 \x01(\x02\x12\x0c\n\x04\x62lue\x18\x03 \x01(\x02\x12\r\n\x05\x61lpha\x18\x04 \x01(\x02"A\n\x0e\x41ttachmentInfo\x12\x1d\n\x15\x61ttachment_identifier\x18\x01 \x01(\t\x12\x10\n\x08type_uti\x18\x02 \x01(\t'
+)
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, "notestore_pb2", _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+    DESCRIPTOR._loaded_options = None
+    _globals["_NOTESTOREPROTO"]._serialized_start = 30
+    _globals["_NOTESTOREPROTO"]._serialized_end = 85
+    _globals["_DOCUMENT"]._serialized_start = 87
+    _globals["_DOCUMENT"]._serialized_end = 128
+    _globals["_NOTE"]._serialized_start = 130
+    _globals["_NOTE"]._serialized_end = 203
+    _globals["_ATTRIBUTERUN"]._serialized_start = 206
+    _globals["_ATTRIBUTERUN"]._serialized_end = 503
+    _globals["_PARAGRAPHSTYLE"]._serialized_start = 506
+    _globals["_PARAGRAPHSTYLE"]._serialized_end = 646
+    _globals["_CHECKLIST"]._serialized_start = 648
+    _globals["_CHECKLIST"]._serialized_end = 687
+    _globals["_FONT"]._serialized_start = 689
+    _globals["_FONT"]._serialized_end = 754
+    _globals["_COLOR"]._serialized_start = 756
+    _globals["_COLOR"]._serialized_end = 820
+    _globals["_ATTACHMENTINFO"]._serialized_start = 822
+    _globals["_ATTACHMENTINFO"]._serialized_end = 887
+# @@protoc_insertion_point(module_scope)

notesctl-1.0.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: notesctl
+Version: 1.0.0
+Summary: Export Apple iCloud Notes to Markdown files safely
+Project-URL: Homepage, https://github.com/jwmoss/notesctl
+Project-URL: Repository, https://github.com/jwmoss/notesctl
+Project-URL: Documentation, https://github.com/jwmoss/notesctl#readme
+Project-URL: Issues, https://github.com/jwmoss/notesctl/issues
+Project-URL: Changelog, https://github.com/jwmoss/notesctl/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: apple,export,icloud,markdown,notes
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: protobuf>=4.25.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: grpcio-tools>=1.60.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: types-pillow>=10.0.0; extra == 'dev'
+Requires-Dist: types-protobuf>=4.24.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# notesctl
+
+Export Apple iCloud Notes to Markdown files safely.
+
+## Features
+
+- **Safe**: Copies database before reading, uses read-only mode
+- **Complete**: Exports text, formatting, and attachments
+- **Organized**: Groups notes by folder with YAML frontmatter
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv pip install .
+
+# Or install in development mode
+uv pip install -e ".[dev]"
+```
+
+## Usage
+
+```bash
+# Export all notes
+uv run notesctl export -o ~/notes-backup
+
+# Export specific folder
+uv run notesctl export --folder "Work" -o ~/work-notes
+
+# Preview without writing (safe)
+uv run notesctl export --dry-run
+
+# List notes
+uv run notesctl list-notes
+
+# List folders
+uv run notesctl list-folders
+
+# Show statistics
+uv run notesctl stats
+```
+
+## Safety
+
+This tool prioritizes safety:
+
+1. **Copy-first**: Database files are copied to temp directory before reading
+2. **Read-only**: SQLite connection uses URI mode=ro
+3. **SELECT only**: All queries are validated to be SELECT statements
+4. **Dry-run mode**: Preview exports without writing files
+
+## Development
+
+```bash
+# Install dev dependencies
+uv pip install -e ".[dev]"
+
+# Run tests
+uv run pytest
+
+# Run linter
+uv run ruff check src tests
+
+# Run type checker
+uv run mypy src
+
+# Format code
+uv run ruff format src tests
+```
+
+## Requirements
+
+- macOS with Apple Notes
+- Python 3.11+
+- uv (recommended) or pip

notesctl-1.0.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+notesctl/__init__.py,sha256=X-odR8GWwfgOrw-lzonDw9SG4nu-u6EaQuHBf8NROTc,64
+notesctl/cli.py,sha256=qnpGGG8e5CzN2H24ter_IfxrfzlDOIHIiGz12VyHkrk,7838
+notesctl/exporter.py,sha256=ll0jUZSg_oXoZ1csZ1ypVO7mHkxfez5Fx6DjVrjnFf0,7711
+notesctl/converter/__init__.py,sha256=uXGQKdQXqyLHZmvXwKL6vXEAW6vJzLAbI34SzbPpNCM,109
+notesctl/converter/markdown.py,sha256=zT5oRPBwx_P_rvNgoi_qXUe-p-D0bey9T1cyXFYkRe8,8032
+notesctl/database/__init__.py,sha256=Ku774zaf2ikCCEgxBT1EWR3BSmdGMkyb3Cd3ldIYOzw,264
+notesctl/database/connection.py,sha256=g6w93I1ln5YjHt0FMSGT8u5aBw3mIknLeLswKOHYEfQ,5154
+notesctl/database/models.py,sha256=EknKwfBoTqg_UNo_EjGGOGH1c_svQZPuC870uDuvUqo,2216
+notesctl/database/queries.py,sha256=PloMefQqlL3J1y5iLeDYfEO1x08nvrWDhAOeyL_p8PM,7796
+notesctl/parser/__init__.py,sha256=NGCner72eO9JJcf5BqRYeB-vPvjDDTpfLhBtnbBWoe8,127
+notesctl/parser/note_parser.py,sha256=Vw0VbYSUcYNq4a_1kT-xwkjYID6g_fgEgPDE20TE6es,7726
+notesctl/parser/protobuf/__init__.py,sha256=m876LJ-X14pTvjQMtViUYOCcOXGSLd3HZVQ2iTi_pWw,124
+notesctl/parser/protobuf/notestore_pb2.py,sha256=gdPQL7rlbwbiV6_9lhFxj8kHhRo1Jeay-bEG4B7S5Ps,3614
+notesctl-1.0.0.dist-info/METADATA,sha256=nFiXSZJr0xEPxCm2BFqU3_t5YZBNppRV2bIRmSEYt5Y,2927
+notesctl-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+notesctl-1.0.0.dist-info/entry_points.txt,sha256=1Ebiz6QJFgcSPZ06R477NxNbc5J_smznlV_jrqsTxpE,46
+notesctl-1.0.0.dist-info/licenses/LICENSE,sha256=Pz2eACSxkhsGfW9_iN60pgy-enjnbGTj8df8O3ebnQQ,16726
+notesctl-1.0.0.dist-info/RECORD,,

notesctl-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

notesctl-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+notesctl = notesctl.cli:app