# Apple Notes Parser
A Python library for reading and parsing Apple Notes SQLite databases. This library extracts data from Apple Notes SQLite stores, including support for reading tags on notes and finding notes that have specific tags.
This is a python implementation of some of the functionality found in [Apple Cloud Notes Parser](https://github.com/threeplanetssoftware/apple_cloud_notes_parser). If you can use Ruby and need a more full featured solution, I recommend trying Apple Cloud Notes Parser.
See also my companion project [macnotesapp](https://github.com/rhettbull/macnotesapp) which uses AppleScript to interact with the Notes app including creating and modifying notes. Apple Notes Parser only supports reading and parsing Apple Notes databases.
## Features
- **Full Database Parsing**: Read all accounts, folders, and notes from Apple Notes databases
- **Protobuf Support**: Parse compressed note data using Protocol Buffers
- **Tag Extraction**: Automatically extract hashtags from note content
- **Tag Filtering**: Find notes by specific tags or combinations of tags
- **Mention Support**: Extract and search for @mentions in notes
- **Link Extraction**: Find and filter notes containing URLs
- **Attachment Support**: Extract attachment metadata and filter notes by attachment type
- **Multi-Version Support**: Works with macOS 10.11+ Notes databases
- **Search Functionality**: Full-text search across note content
- **Export Capabilities**: Export data to JSON format
- **Metadata Access**: Access creation dates, modification dates, pinned status, etc.
## Installation
### Using uv (recommended)
```bash
uv pip install apple-notes-parser
```
### Using pip
```bash
pip install apple-notes-parser
```
## Quick Start
```python
from apple_notes_parser import AppleNotesParser
# Initialize parser with your Notes database
parser = AppleNotesParser()
# Load all data
parser.load_data()
# Get basic statistics
print(f"Found {len(parser.notes)} notes in {len(parser.folders)} folders")
# Find notes with specific tags
work_notes = parser.get_notes_by_tag("work")
print(f"Found {len(work_notes)} notes tagged with #work")
# Search for notes containing text
important_notes = parser.search_notes("important")
# Get all unique tags
all_tags = parser.get_all_tags()
print(f"All tags: {', '.join(all_tags)}")
```
## Database Location
The Apple Notes database is typically located at:
```
~/Library/Group Containers/group.com.apple.notes/NoteStore.sqlite
```
## Command Line Interface (CLI)
The package includes a simpl command-line interface for working with Apple Notes databases without writing any code. The CLI provides access to all major functionality including listing notes, searching, exporting data, and analyzing attachments.
### Installation and Access
After installing the package, the CLI is available as `apple-notes-parser`:
```bash
# Install from PyPI
pip install apple-notes-parser
# Use the CLI
apple-notes-parser --help
```
### CLI Commands Overview
The CLI provides several commands for different use cases:
- **`list`** - List and filter notes
- **`search`** - Search notes by text content
- **`export`** - Export notes to JSON format
- **`stats`** - Show database statistics and summary
- **`attachments`** - List and extract attachments
- **`tags`** - Analyze and list hashtags
### Global Options
All commands support these global options:
```bash
apple-notes-parser [--database PATH] [--version] COMMAND [OPTIONS]
```
- `--database`, `-d` - Path to NoteStore.sqlite file (auto-detected if not specified)
- `--version` - Show version information
- `--help` - Show help message
### CLI Usage Examples
**Quick Database Overview:**
```bash
apple-notes-parser stats --verbose
```
**Find Work-Related Notes:**
```bash
apple-notes-parser list --folder "Work" --tag "urgent"
```
**Find Notes About Specific Topic:**
```bash
apple-notes-parser search "budget meeting" --content
```
**Save all images from notes**
```bash
apple-notes-parser attachments --type image --save ./images
```
**Custom Database Path:**
```bash
# Use specific database file
apple-notes-parser --database /path/to/custom/NoteStore.sqlite stats
```
## API Reference
### Main Parser Class
#### `AppleNotesParser(database_path: str)`
Main parser class for Apple Notes databases.
**Methods:**
- `load_data()` - Load all data from the database
- `notes` - Get all notes (list[Note])
- `folders` - Get all folders (list[Folder])
- `accounts` - Get all accounts (list[Account])
### Tag and Content Filtering
- `get_notes_by_tag(tag: str)` - Get notes with a specific tag
- `get_notes_by_tags(tags: list[str], match_all: bool = False)` - Get notes with multiple tags
- `get_all_tags()` - Get all unique hashtags
- `get_tag_counts()` - Get usage count for each tag
### Search and Filter
- `search_notes(query: str, case_sensitive: bool = False)` - Full-text search
- `get_notes_by_folder(folder_name: str)` - Get notes in specific folder
- `get_notes_by_account(account_name: str)` - Get notes in specific account
- `get_note_by_applescript_id(applescript_id: str)` - Get note by AppleScript ID (e.g. "x-coredata://5A2C18B7-767B-41A9-BF71-E4E966775D32/ICNote/p4884")
- `get_pinned_notes()` - Get all pinned notes
- `get_protected_notes()` - Get password-protected notes
- `filter_notes(filter_func: Callable[[Note], bool])` - Custom filtering
### Mentions and Links
- `get_notes_with_mentions()` - Get notes containing @mentions
- `get_notes_by_mention(mention: str)` - Get notes mentioning specific user
- `get_notes_with_links()` - Get notes containing URLs
- `get_notes_by_link_domain(domain: str)` - Get notes with links to specific domain
### Attachments
- `get_notes_with_attachments()` - Get notes that have attachments
- `get_notes_by_attachment_type(attachment_type: str)` - Get notes with specific attachment types (image, video, audio, document)
- `get_all_attachments()` - Get all attachments across all notes
### Export
- `export_notes_to_dict(include_content: bool = True)` - Export to dictionary/JSON
### Data Models
#### Note
- `id: int` - Database primary key
- `note_id: int` - Note identifier
- `title: str` - Note title
- `content: str` - Note text content
- `creation_date: datetime` - When note was created
- `modification_date: datetime` - When note was last modified
- `account: Account` - Owning account
- `folder: Folder` - Containing folder
- `is_pinned: bool` - Whether note is pinned
- `is_password_protected: bool` - Whether note is encrypted
- `uuid: str` - Unique identifier
- `applescript_id: str` - AppleScript ID of the note (this is the unique identifier used by AppleScript to interact with the note)
- `tags: list[str]` - Hashtags found in note
- `mentions: list[str]` - @mentions found in note
- `links: list[str]` - URLs found in note
- `attachments: list[Attachment]` - File attachments in note
- `get_folder_path(): str` - Returns the path of the folder the note is in
- `get_attachments_by_extension(extension: str) -> list[Attachment]` - Returns a list of attachments with the specified extension
- `get_attachments_by_type(attachment_type: str) -> list[Attachment]` - Returns a list of attachments with the specified type
#### Folder
- `name: str` - Folder name
- `account: Account` - Owning account
- `uuid: str` - Unique identifier
- `parent_id: int` - Parent folder ID (for nested folders)
- `get_path(): str` - Returns the path of the folder
- `get_parent(): Folder` - Returns the parent folder
- `is_root(): bool` - Returns whether the folder is the root folder
#### Attachment
- `id: int` - Database primary key
- `filename: str` - Attachment filename (e.g., "document.pdf")
- `file_size: int` - File size in bytes
- `type_uti: str` - Uniform Type Identifier (e.g., "com.adobe.pdf")
- `note_id: int` - Parent note ID
- `creation_date: datetime` - When attachment was created
- `modification_date: datetime` - When attachment was last modified
- `uuid: str` - Unique identifier
- `is_remote: bool` - Whether attachment is stored remotely
- `remote_url: str` - Remote URL if applicable
##### Attachment Properties
- `file_extension: str` - File extension (e.g., "pdf", "jpg")
- `mime_type: str` - MIME type (e.g., "application/pdf", "image/jpeg")
- `is_image: bool` - Whether attachment is an image
- `is_video: bool` - Whether attachment is a video
- `is_audio: bool` - Whether attachment is audio
- `is_document: bool` - Whether attachment is a document
#### Account
- `id: int` - Database primary key
- `name: str` - Account name (e.g., "iCloud", "On My Mac")
- `identifier: str` - Account identifier
- `user_record_name: str` - CloudKit user record name
## Examples
### Find Notes by Tags
```python
# Find notes with specific tag
work_notes = parser.get_notes_by_tag("work")
# Find notes with multiple tags (OR logic)
important_or_urgent = parser.get_notes_by_tags(["important", "urgent"], match_all=False)
# Find notes with multiple tags (AND logic)
work_and_important = parser.get_notes_by_tags(["work", "important"], match_all=True)
# Get tag statistics
tag_counts = parser.get_tag_counts()
for tag, count in tag_counts.items():
print(f"#{tag}: {count} notes")
```
### Search and Filter
```python
# Full-text search
meeting_notes = parser.search_notes("meeting")
# Custom filtering
recent_notes = parser.filter_notes(
lambda note: note.modification_date and
note.modification_date > datetime.now() - timedelta(days=7)
)
# Find notes with attachments
notes_with_attachments = parser.get_notes_with_attachments()
print(f"Found {len(notes_with_attachments)} notes with attachments")
# Find notes with specific attachment types
image_notes = parser.get_notes_by_attachment_type("image")
document_notes = parser.get_notes_by_attachment_type("document")
video_notes = parser.get_notes_by_attachment_type("video")
audio_notes = parser.get_notes_by_attachment_type("audio")
```
### Working with Attachments
```python
# Get all notes that have attachments
notes_with_attachments = parser.get_notes_with_attachments()
print(f"Found {len(notes_with_attachments)} notes with attachments")
# Filter by attachment type
image_notes = parser.get_notes_by_attachment_type("image")
document_notes = parser.get_notes_by_attachment_type("document")
video_notes = parser.get_notes_by_attachment_type("video")
audio_notes = parser.get_notes_by_attachment_type("audio")
# Get all attachments across all notes
all_attachments = parser.get_all_attachments()
for attachment in all_attachments:
print(f"{attachment.filename} ({attachment.file_size} bytes) - {attachment.mime_type}")
# Work with individual note attachments
for note in notes_with_attachments:
print(f"Note: {note.title}")
for attachment in note.attachments:
print(f" - {attachment.filename}")
print(f" Size: {attachment.file_size} bytes")
print(f" Type: {attachment.type_uti}")
print(f" MIME: {attachment.mime_type}")
print(f" Is Image: {attachment.is_image}")
print(f" Is Document: {attachment.is_document}")
# Filter by file extension
if attachment.file_extension == "pdf":
print(f" Found PDF: {attachment.filename}")
```
### Export Data
```python
# Export all data to JSON
data = parser.export_notes_to_dict()
with open("notes_backup.json", "w") as f:
json.dump(data, f, indent=2)
# Export without content (for privacy)
metadata_only = parser.export_notes_to_dict(include_content=False)
```
## Technical Details
The library uses Protocol Buffers to parse compressed note data. See [Revisiting Apple Notes (6): The Protobuf](https://ciofecaforensics.com/2020/09/18/apple-notes-revisited-protobuf/) for more details about how Apple Notes stores data.
## Limitations
- **Encrypted Notes**: Password-protected notes cannot be decrypted without the password
- **Rich Formatting**: Complex formatting information is not fully preserved in plain text output
## Development and Building
### Prerequisites
For using the library (end users), you only need:
- Python 3.11+
- Dependencies are automatically installed via `uv`:
For development and building, you need:
- Python 3.11+
- `uv` package manager (recommended)
- Development dependencies including `grpcio-tools` (for protobuf code generation, if needed)
### Development Setup
1. **Clone the repository:**
```bash
git clone git@github.com:RhetTbull/apple-notes-parser.git
cd apple-notes-parser
```
2. **Install in development mode with uv (recommended):**
```bash
uv sync --all-extras
```
### Running Tests
The project includes a comprehensive test suite with 54+ tests:
```bash
# Run all tests
uv run pytest
# Run specific test file
uv run pytest tests/test_real_database.py
# Run tests with coverage
uv run pytest --cov=apple_notes_parser
```
### Code Quality and Linting
The project uses modern Python tooling for code quality assurance:
#### Running Ruff (Linting and Formatting)
[Ruff](https://docs.astral.sh/ruff/) is used for fast linting and import sorting:
```bash
# Check for linting issues
uv run ruff check src/
# Automatically fix linting issues (safe fixes only)
uv run ruff check --fix src/
# Apply formatting
uv run ruff format src/
# Check imports are properly sorted
uv run ruff check --select I src/
```
The script `./check` in the project root directory is a convenient wrapper for running all linting and formatting checks and automatically fixing safe issues:
```bash
uv run ./check --verbose
```
#### Running MyPy (Type Checking)
[MyPy](https://mypy.readthedocs.io/) is used for static type checking:
```bash
# Run type checking on the entire codebase
uv run mypy src/apple_notes_parser/
# Run type checking with verbose output
uv run mypy --verbose src/apple_notes_parser/
# Check specific file
uv run mypy src/apple_notes_parser/parser.py
```
#### Pre-commit Workflow
Before submitting code, run the complete quality check using our automated scripts:
```bash
./check
```
### Protobuf Code Generation
**Important:** The protobuf Python files (`notestore_pb2.py`) are pre-generated and included in the repository. You typically don't need to regenerate them unless:
- You're modifying the `notestore.proto` file
- You're updating to a newer protobuf version
- You encounter protobuf version compatibility warnings
#### How to Regenerate Protobuf Files
1. **Ensure you have the required development tools:**
```bash
uv sync --all-extras # Install development dependencies including grpcio-tools
```
2. **Navigate to the protobuf source directory:**
```bash
cd src/apple_notes_parser
```
3. **Regenerate the Python protobuf files using the automated script:**
```bash
python scripts/regenerate_protobuf.py
```
Or manually:
```bash
cd src/apple_notes_parser
python -m grpc_tools.protoc --proto_path=. --python_out=. notestore.proto
cd ../.. # Back to project root
uv run pytest # Verify everything works
```
The automated script will:
- Regenerate the protobuf files
- Verify the version was updated correctly
- Run the test suite to ensure compatibility
### Adding Support for New Database Versions
The library is designed to be extensible for future macOS versions:
1. **Add new test database:**
```bash
# Place new database in tests/data/
cp /path/to/NoteStore-macOS-16.sqlite tests/data/
```
2. **Update test fixtures in `tests/conftest.py`:**
```python
@pytest.fixture(params=["macos_15", "macos_16"]) # Add new version
def versioned_database(request):
if request.param == "macos_16":
database_path = Path(__file__).parent / "data" / "NoteStore-macOS-16.sqlite"
# ... handle new version
```
3. **Update version detection in `src/apple_notes_parser/database.py`:**
```python
def get_macos_version(self) -> int:
# Add detection logic for new version
if "NEW_COLUMN_NAME" in columns:
self._macos_version = 26 # New version number
```
4. **Run tests to ensure compatibility:**
```bash
uv run pytest tests/test_version_agnostic.py
```
### Building and Distribution
To build the package for distribution:
```bash
# Install build tools
uv add --dev build
# Build the package
uv run python -m build
# This creates:
# dist/apple_notes_parser-0.1.0-py3-none-any.whl
# dist/apple_notes_parser-0.1.0.tar.gz
```
### Dependency Management
The project uses these key dependencies:
- **Runtime dependencies** (required for end users):
- `protobuf>=6.31.1` - Protocol buffer runtime for parsing compressed note data
- **Development dependencies** (for contributors):
- `pytest>=8.0.0` - Testing framework
- `pytest-cov>=4.0.0` - Coverage reporting
- `ruff>=0.8.0` - Fast Python linter and formatter
- `mypy>=1.13.0` - Static type checker
- `grpcio-tools>=1.74.0` - Protocol buffer compiler for code generation
- `types-protobuf>=6.30.2.20250703` - Type stubs for protobuf
### Troubleshooting
**Protobuf version warnings:**
- Regenerate protobuf files using the steps above
- Ensure `protobuf` and `grpcio-tools` are at compatible versions (install dev dependencies with `uv sync --dev`)
**Test failures:**
- Ensure you have the real test database in `tests/data/`
- Check that your Python version is 3.11+
- Try running `uv sync --all-extras` to refresh dependencies
**Import errors:**
- Verify installation with `uv run python -c "import apple_notes_parser; print('OK')"`
- Check that you're in the correct virtual environment
## Contributing
Contributions are welcome! Please feel free to submit pull requests or open issues.
### Contribution Guidelines
1. **Fork the repository** and create a feature branch
2. **Write tests** for any new functionality
3. **Run quality checks** before submitting:
```bash
uv run ./check
```
4. **Follow existing code style** and patterns
5. **Update documentation** for user-facing changes
6. **Submit a pull request** with a clear description
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Acknowledgments
This library builds upon the excellent work from:
- [threeplanetssoftware/apple_cloud_notes_parser](https://github.com/threeplanetssoftware/apple_cloud_notes_parser) - Ruby implementation and protobuf definitions
- [HamburgChimps/apple-notes-liberator](https://github.com/HamburgChimps/apple-notes-liberator) - Java implementation
- [Ciofeca Forensics](https://ciofecaforensics.com/) - Technical research on Apple Notes storage format
This project was built with assistance of AI, specifically using [Claude Code](https://www.anthropic.com/claude-code)
Raw data
{
"_id": null,
"home_page": null,
"name": "apple-notes-parser",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Rhet Turnbull <rturnbull+git@gmail.com>",
"keywords": "apple, cli, database, extraction, macos, notes, parser, protobuf, sqlite",
"author": null,
"author_email": "Rhet Turnbull <rturnbull+git@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/fc/c1/939bac79729bcb32aaef71983ad4e1ebdefc77636b6506197baa068bd4a9/apple_notes_parser-0.2.0.tar.gz",
"platform": null,
"description": "# Apple Notes Parser\n\nA Python library for reading and parsing Apple Notes SQLite databases. This library extracts data from Apple Notes SQLite stores, including support for reading tags on notes and finding notes that have specific tags.\n\nThis is a python implementation of some of the functionality found in [Apple Cloud Notes Parser](https://github.com/threeplanetssoftware/apple_cloud_notes_parser). If you can use Ruby and need a more full featured solution, I recommend trying Apple Cloud Notes Parser.\n\nSee also my companion project [macnotesapp](https://github.com/rhettbull/macnotesapp) which uses AppleScript to interact with the Notes app including creating and modifying notes. Apple Notes Parser only supports reading and parsing Apple Notes databases.\n\n## Features\n\n- **Full Database Parsing**: Read all accounts, folders, and notes from Apple Notes databases\n- **Protobuf Support**: Parse compressed note data using Protocol Buffers\n- **Tag Extraction**: Automatically extract hashtags from note content\n- **Tag Filtering**: Find notes by specific tags or combinations of tags\n- **Mention Support**: Extract and search for @mentions in notes\n- **Link Extraction**: Find and filter notes containing URLs\n- **Attachment Support**: Extract attachment metadata and filter notes by attachment type\n- **Multi-Version Support**: Works with macOS 10.11+ Notes databases\n- **Search Functionality**: Full-text search across note content\n- **Export Capabilities**: Export data to JSON format\n- **Metadata Access**: Access creation dates, modification dates, pinned status, etc.\n\n## Installation\n\n### Using uv (recommended)\n\n```bash\nuv pip install apple-notes-parser\n```\n\n### Using pip\n\n```bash\npip install apple-notes-parser\n```\n\n## Quick Start\n\n```python\nfrom apple_notes_parser import AppleNotesParser\n\n# Initialize parser with your Notes database\nparser = AppleNotesParser()\n\n# Load all data\nparser.load_data()\n\n# Get basic statistics\nprint(f\"Found {len(parser.notes)} notes in {len(parser.folders)} folders\")\n\n# Find notes with specific tags\nwork_notes = parser.get_notes_by_tag(\"work\")\nprint(f\"Found {len(work_notes)} notes tagged with #work\")\n\n# Search for notes containing text\nimportant_notes = parser.search_notes(\"important\")\n\n# Get all unique tags\nall_tags = parser.get_all_tags()\nprint(f\"All tags: {', '.join(all_tags)}\")\n```\n\n## Database Location\n\nThe Apple Notes database is typically located at:\n\n```\n~/Library/Group Containers/group.com.apple.notes/NoteStore.sqlite\n```\n\n## Command Line Interface (CLI)\n\nThe package includes a simpl command-line interface for working with Apple Notes databases without writing any code. The CLI provides access to all major functionality including listing notes, searching, exporting data, and analyzing attachments.\n\n### Installation and Access\n\nAfter installing the package, the CLI is available as `apple-notes-parser`:\n\n```bash\n# Install from PyPI\npip install apple-notes-parser\n\n# Use the CLI\napple-notes-parser --help\n```\n\n### CLI Commands Overview\n\nThe CLI provides several commands for different use cases:\n\n- **`list`** - List and filter notes\n- **`search`** - Search notes by text content\n- **`export`** - Export notes to JSON format\n- **`stats`** - Show database statistics and summary\n- **`attachments`** - List and extract attachments\n- **`tags`** - Analyze and list hashtags\n\n### Global Options\n\nAll commands support these global options:\n\n```bash\napple-notes-parser [--database PATH] [--version] COMMAND [OPTIONS]\n```\n\n- `--database`, `-d` - Path to NoteStore.sqlite file (auto-detected if not specified)\n- `--version` - Show version information\n- `--help` - Show help message\n\n### CLI Usage Examples\n\n**Quick Database Overview:**\n```bash\napple-notes-parser stats --verbose\n```\n\n**Find Work-Related Notes:**\n```bash\napple-notes-parser list --folder \"Work\" --tag \"urgent\"\n```\n\n**Find Notes About Specific Topic:**\n```bash\napple-notes-parser search \"budget meeting\" --content\n```\n\n**Save all images from notes**\n```bash\napple-notes-parser attachments --type image --save ./images\n```\n\n**Custom Database Path:**\n```bash\n# Use specific database file\napple-notes-parser --database /path/to/custom/NoteStore.sqlite stats\n```\n\n## API Reference\n\n### Main Parser Class\n\n#### `AppleNotesParser(database_path: str)`\n\nMain parser class for Apple Notes databases.\n\n**Methods:**\n\n- `load_data()` - Load all data from the database\n- `notes` - Get all notes (list[Note])\n- `folders` - Get all folders (list[Folder])\n- `accounts` - Get all accounts (list[Account])\n\n### Tag and Content Filtering\n\n- `get_notes_by_tag(tag: str)` - Get notes with a specific tag\n- `get_notes_by_tags(tags: list[str], match_all: bool = False)` - Get notes with multiple tags\n- `get_all_tags()` - Get all unique hashtags\n- `get_tag_counts()` - Get usage count for each tag\n\n### Search and Filter\n\n- `search_notes(query: str, case_sensitive: bool = False)` - Full-text search\n- `get_notes_by_folder(folder_name: str)` - Get notes in specific folder\n- `get_notes_by_account(account_name: str)` - Get notes in specific account\n- `get_note_by_applescript_id(applescript_id: str)` - Get note by AppleScript ID (e.g. \"x-coredata://5A2C18B7-767B-41A9-BF71-E4E966775D32/ICNote/p4884\")\n- `get_pinned_notes()` - Get all pinned notes\n- `get_protected_notes()` - Get password-protected notes\n- `filter_notes(filter_func: Callable[[Note], bool])` - Custom filtering\n\n### Mentions and Links\n\n- `get_notes_with_mentions()` - Get notes containing @mentions\n- `get_notes_by_mention(mention: str)` - Get notes mentioning specific user\n- `get_notes_with_links()` - Get notes containing URLs\n- `get_notes_by_link_domain(domain: str)` - Get notes with links to specific domain\n\n### Attachments\n\n- `get_notes_with_attachments()` - Get notes that have attachments\n- `get_notes_by_attachment_type(attachment_type: str)` - Get notes with specific attachment types (image, video, audio, document)\n- `get_all_attachments()` - Get all attachments across all notes\n\n### Export\n\n- `export_notes_to_dict(include_content: bool = True)` - Export to dictionary/JSON\n\n### Data Models\n\n#### Note\n- `id: int` - Database primary key\n- `note_id: int` - Note identifier\n- `title: str` - Note title\n- `content: str` - Note text content\n- `creation_date: datetime` - When note was created\n- `modification_date: datetime` - When note was last modified\n- `account: Account` - Owning account\n- `folder: Folder` - Containing folder\n- `is_pinned: bool` - Whether note is pinned\n- `is_password_protected: bool` - Whether note is encrypted\n- `uuid: str` - Unique identifier\n- `applescript_id: str` - AppleScript ID of the note (this is the unique identifier used by AppleScript to interact with the note)\n- `tags: list[str]` - Hashtags found in note\n- `mentions: list[str]` - @mentions found in note\n- `links: list[str]` - URLs found in note\n- `attachments: list[Attachment]` - File attachments in note\n- `get_folder_path(): str` - Returns the path of the folder the note is in\n- `get_attachments_by_extension(extension: str) -> list[Attachment]` - Returns a list of attachments with the specified extension\n- `get_attachments_by_type(attachment_type: str) -> list[Attachment]` - Returns a list of attachments with the specified type\n\n#### Folder\n- `name: str` - Folder name\n- `account: Account` - Owning account\n- `uuid: str` - Unique identifier\n- `parent_id: int` - Parent folder ID (for nested folders)\n- `get_path(): str` - Returns the path of the folder\n- `get_parent(): Folder` - Returns the parent folder\n- `is_root(): bool` - Returns whether the folder is the root folder\n\n#### Attachment\n- `id: int` - Database primary key\n- `filename: str` - Attachment filename (e.g., \"document.pdf\")\n- `file_size: int` - File size in bytes\n- `type_uti: str` - Uniform Type Identifier (e.g., \"com.adobe.pdf\")\n- `note_id: int` - Parent note ID\n- `creation_date: datetime` - When attachment was created\n- `modification_date: datetime` - When attachment was last modified\n- `uuid: str` - Unique identifier\n- `is_remote: bool` - Whether attachment is stored remotely\n- `remote_url: str` - Remote URL if applicable\n\n##### Attachment Properties\n- `file_extension: str` - File extension (e.g., \"pdf\", \"jpg\")\n- `mime_type: str` - MIME type (e.g., \"application/pdf\", \"image/jpeg\")\n- `is_image: bool` - Whether attachment is an image\n- `is_video: bool` - Whether attachment is a video\n- `is_audio: bool` - Whether attachment is audio\n- `is_document: bool` - Whether attachment is a document\n\n#### Account\n- `id: int` - Database primary key\n- `name: str` - Account name (e.g., \"iCloud\", \"On My Mac\")\n- `identifier: str` - Account identifier\n- `user_record_name: str` - CloudKit user record name\n\n## Examples\n\n### Find Notes by Tags\n\n```python\n# Find notes with specific tag\nwork_notes = parser.get_notes_by_tag(\"work\")\n\n# Find notes with multiple tags (OR logic)\nimportant_or_urgent = parser.get_notes_by_tags([\"important\", \"urgent\"], match_all=False)\n\n# Find notes with multiple tags (AND logic)\nwork_and_important = parser.get_notes_by_tags([\"work\", \"important\"], match_all=True)\n\n# Get tag statistics\ntag_counts = parser.get_tag_counts()\nfor tag, count in tag_counts.items():\n print(f\"#{tag}: {count} notes\")\n```\n\n### Search and Filter\n\n```python\n# Full-text search\nmeeting_notes = parser.search_notes(\"meeting\")\n\n# Custom filtering\nrecent_notes = parser.filter_notes(\n lambda note: note.modification_date and\n note.modification_date > datetime.now() - timedelta(days=7)\n)\n\n# Find notes with attachments\nnotes_with_attachments = parser.get_notes_with_attachments()\nprint(f\"Found {len(notes_with_attachments)} notes with attachments\")\n\n# Find notes with specific attachment types\nimage_notes = parser.get_notes_by_attachment_type(\"image\")\ndocument_notes = parser.get_notes_by_attachment_type(\"document\")\nvideo_notes = parser.get_notes_by_attachment_type(\"video\")\naudio_notes = parser.get_notes_by_attachment_type(\"audio\")\n```\n\n### Working with Attachments\n\n```python\n# Get all notes that have attachments\nnotes_with_attachments = parser.get_notes_with_attachments()\nprint(f\"Found {len(notes_with_attachments)} notes with attachments\")\n\n# Filter by attachment type\nimage_notes = parser.get_notes_by_attachment_type(\"image\")\ndocument_notes = parser.get_notes_by_attachment_type(\"document\")\nvideo_notes = parser.get_notes_by_attachment_type(\"video\")\naudio_notes = parser.get_notes_by_attachment_type(\"audio\")\n\n# Get all attachments across all notes\nall_attachments = parser.get_all_attachments()\nfor attachment in all_attachments:\n print(f\"{attachment.filename} ({attachment.file_size} bytes) - {attachment.mime_type}\")\n\n# Work with individual note attachments\nfor note in notes_with_attachments:\n print(f\"Note: {note.title}\")\n for attachment in note.attachments:\n print(f\" - {attachment.filename}\")\n print(f\" Size: {attachment.file_size} bytes\")\n print(f\" Type: {attachment.type_uti}\")\n print(f\" MIME: {attachment.mime_type}\")\n print(f\" Is Image: {attachment.is_image}\")\n print(f\" Is Document: {attachment.is_document}\")\n\n # Filter by file extension\n if attachment.file_extension == \"pdf\":\n print(f\" Found PDF: {attachment.filename}\")\n```\n\n### Export Data\n\n```python\n# Export all data to JSON\ndata = parser.export_notes_to_dict()\nwith open(\"notes_backup.json\", \"w\") as f:\n json.dump(data, f, indent=2)\n\n# Export without content (for privacy)\nmetadata_only = parser.export_notes_to_dict(include_content=False)\n```\n\n## Technical Details\n\nThe library uses Protocol Buffers to parse compressed note data. See [Revisiting Apple Notes (6): The Protobuf](https://ciofecaforensics.com/2020/09/18/apple-notes-revisited-protobuf/) for more details about how Apple Notes stores data.\n\n## Limitations\n\n- **Encrypted Notes**: Password-protected notes cannot be decrypted without the password\n- **Rich Formatting**: Complex formatting information is not fully preserved in plain text output\n\n## Development and Building\n\n### Prerequisites\n\nFor using the library (end users), you only need:\n- Python 3.11+\n- Dependencies are automatically installed via `uv`:\n\nFor development and building, you need:\n- Python 3.11+\n- `uv` package manager (recommended)\n- Development dependencies including `grpcio-tools` (for protobuf code generation, if needed)\n\n### Development Setup\n\n1. **Clone the repository:**\n ```bash\n git clone git@github.com:RhetTbull/apple-notes-parser.git\n cd apple-notes-parser\n ```\n\n2. **Install in development mode with uv (recommended):**\n ```bash\n uv sync --all-extras\n ```\n\n### Running Tests\n\nThe project includes a comprehensive test suite with 54+ tests:\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run specific test file\nuv run pytest tests/test_real_database.py\n\n# Run tests with coverage\nuv run pytest --cov=apple_notes_parser\n```\n\n### Code Quality and Linting\n\nThe project uses modern Python tooling for code quality assurance:\n\n#### Running Ruff (Linting and Formatting)\n\n[Ruff](https://docs.astral.sh/ruff/) is used for fast linting and import sorting:\n\n```bash\n# Check for linting issues\nuv run ruff check src/\n\n# Automatically fix linting issues (safe fixes only)\nuv run ruff check --fix src/\n\n# Apply formatting\nuv run ruff format src/\n\n# Check imports are properly sorted\nuv run ruff check --select I src/\n```\n\nThe script `./check` in the project root directory is a convenient wrapper for running all linting and formatting checks and automatically fixing safe issues:\n\n```bash\nuv run ./check --verbose\n```\n\n#### Running MyPy (Type Checking)\n\n[MyPy](https://mypy.readthedocs.io/) is used for static type checking:\n\n```bash\n# Run type checking on the entire codebase\nuv run mypy src/apple_notes_parser/\n\n# Run type checking with verbose output\nuv run mypy --verbose src/apple_notes_parser/\n\n# Check specific file\nuv run mypy src/apple_notes_parser/parser.py\n```\n\n#### Pre-commit Workflow\n\nBefore submitting code, run the complete quality check using our automated scripts:\n\n```bash\n./check\n```\n\n### Protobuf Code Generation\n\n**Important:** The protobuf Python files (`notestore_pb2.py`) are pre-generated and included in the repository. You typically don't need to regenerate them unless:\n\n- You're modifying the `notestore.proto` file\n- You're updating to a newer protobuf version\n- You encounter protobuf version compatibility warnings\n\n#### How to Regenerate Protobuf Files\n\n1. **Ensure you have the required development tools:**\n ```bash\n uv sync --all-extras # Install development dependencies including grpcio-tools\n ```\n\n2. **Navigate to the protobuf source directory:**\n ```bash\n cd src/apple_notes_parser\n ```\n\n3. **Regenerate the Python protobuf files using the automated script:**\n ```bash\n python scripts/regenerate_protobuf.py\n ```\n\n Or manually:\n ```bash\n cd src/apple_notes_parser\n python -m grpc_tools.protoc --proto_path=. --python_out=. notestore.proto\n cd ../.. # Back to project root\n uv run pytest # Verify everything works\n ```\n\nThe automated script will:\n- Regenerate the protobuf files\n- Verify the version was updated correctly\n- Run the test suite to ensure compatibility\n\n### Adding Support for New Database Versions\n\nThe library is designed to be extensible for future macOS versions:\n\n1. **Add new test database:**\n ```bash\n # Place new database in tests/data/\n cp /path/to/NoteStore-macOS-16.sqlite tests/data/\n ```\n\n2. **Update test fixtures in `tests/conftest.py`:**\n ```python\n @pytest.fixture(params=[\"macos_15\", \"macos_16\"]) # Add new version\n def versioned_database(request):\n if request.param == \"macos_16\":\n database_path = Path(__file__).parent / \"data\" / \"NoteStore-macOS-16.sqlite\"\n # ... handle new version\n ```\n\n3. **Update version detection in `src/apple_notes_parser/database.py`:**\n ```python\n def get_macos_version(self) -> int:\n # Add detection logic for new version\n if \"NEW_COLUMN_NAME\" in columns:\n self._macos_version = 26 # New version number\n ```\n\n4. **Run tests to ensure compatibility:**\n ```bash\n uv run pytest tests/test_version_agnostic.py\n ```\n\n### Building and Distribution\n\nTo build the package for distribution:\n\n```bash\n# Install build tools\nuv add --dev build\n\n# Build the package\nuv run python -m build\n\n# This creates:\n# dist/apple_notes_parser-0.1.0-py3-none-any.whl\n# dist/apple_notes_parser-0.1.0.tar.gz\n```\n\n### Dependency Management\n\nThe project uses these key dependencies:\n\n- **Runtime dependencies** (required for end users):\n - `protobuf>=6.31.1` - Protocol buffer runtime for parsing compressed note data\n\n- **Development dependencies** (for contributors):\n - `pytest>=8.0.0` - Testing framework\n - `pytest-cov>=4.0.0` - Coverage reporting\n - `ruff>=0.8.0` - Fast Python linter and formatter\n - `mypy>=1.13.0` - Static type checker\n - `grpcio-tools>=1.74.0` - Protocol buffer compiler for code generation\n - `types-protobuf>=6.30.2.20250703` - Type stubs for protobuf\n\n### Troubleshooting\n\n**Protobuf version warnings:**\n- Regenerate protobuf files using the steps above\n- Ensure `protobuf` and `grpcio-tools` are at compatible versions (install dev dependencies with `uv sync --dev`)\n\n**Test failures:**\n- Ensure you have the real test database in `tests/data/`\n- Check that your Python version is 3.11+\n- Try running `uv sync --all-extras` to refresh dependencies\n\n**Import errors:**\n- Verify installation with `uv run python -c \"import apple_notes_parser; print('OK')\"`\n- Check that you're in the correct virtual environment\n\n## Contributing\n\nContributions are welcome! Please feel free to submit pull requests or open issues.\n\n### Contribution Guidelines\n\n1. **Fork the repository** and create a feature branch\n2. **Write tests** for any new functionality\n3. **Run quality checks** before submitting:\n ```bash\n uv run ./check\n ```\n4. **Follow existing code style** and patterns\n5. **Update documentation** for user-facing changes\n6. **Submit a pull request** with a clear description\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\nThis library builds upon the excellent work from:\n\n- [threeplanetssoftware/apple_cloud_notes_parser](https://github.com/threeplanetssoftware/apple_cloud_notes_parser) - Ruby implementation and protobuf definitions\n- [HamburgChimps/apple-notes-liberator](https://github.com/HamburgChimps/apple-notes-liberator) - Java implementation\n- [Ciofeca Forensics](https://ciofecaforensics.com/) - Technical research on Apple Notes storage format\n\nThis project was built with assistance of AI, specifically using [Claude Code](https://www.anthropic.com/claude-code)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python library for reading and parsing Apple Notes SQLite databases with comprehensive CLI tools",
"version": "0.2.0",
"project_urls": {
"Bug Reports": "https://github.com/rhettbull/apple-notes-parser/issues",
"Documentation": "https://github.com/rhettbull/apple-notes-parser#readme",
"Homepage": "https://github.com/rhettbull/apple-notes-parser",
"Repository": "https://github.com/rhettbull/apple-notes-parser",
"Source Code": "https://github.com/rhettbull/apple-notes-parser"
},
"split_keywords": [
"apple",
" cli",
" database",
" extraction",
" macos",
" notes",
" parser",
" protobuf",
" sqlite"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "90232f1cc4e1bdf408edf5ebe95f9313bb22d8fce348188613e0ba012d74a414",
"md5": "13848528f277954cf016b140be5e581c",
"sha256": "0817af295f49d3561e50bd4a92c7fa8fa53663e4c40c352dd179133b1e27b937"
},
"downloads": -1,
"filename": "apple_notes_parser-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "13848528f277954cf016b140be5e581c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 40305,
"upload_time": "2025-08-03T20:15:17",
"upload_time_iso_8601": "2025-08-03T20:15:17.113794Z",
"url": "https://files.pythonhosted.org/packages/90/23/2f1cc4e1bdf408edf5ebe95f9313bb22d8fce348188613e0ba012d74a414/apple_notes_parser-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fcc1939bac79729bcb32aaef71983ad4e1ebdefc77636b6506197baa068bd4a9",
"md5": "3f2e178bba88bac4d15933370b1dd46a",
"sha256": "a6031d81ec3347c90bf7e53cad30bb09dd0daf5fec9e89cc699c303ad5ed4e9a"
},
"downloads": -1,
"filename": "apple_notes_parser-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "3f2e178bba88bac4d15933370b1dd46a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 3290344,
"upload_time": "2025-08-03T20:15:18",
"upload_time_iso_8601": "2025-08-03T20:15:18.603549Z",
"url": "https://files.pythonhosted.org/packages/fc/c1/939bac79729bcb32aaef71983ad4e1ebdefc77636b6506197baa068bd4a9/apple_notes_parser-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 20:15:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rhettbull",
"github_project": "apple-notes-parser",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "apple-notes-parser"
}
JSON
