remarkablesync 1.0.6__py3-none-any.whl

RemarkableSync.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""
+RemarkableSync - Unified command-line interface
+
+Single entry point for backing up and converting ReMarkable tablet files.
+"""
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+# Check Python version before importing anything else
+if sys.version_info < (3, 11):
+    print("Error: RemarkableSync requires Python 3.11 or higher.")
+    print(f"You are using Python {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")
+    print("\nPlease upgrade your Python installation:")
+    print("  - Download from: https://www.python.org/downloads/")
+    print("  - Or use a package manager (brew, apt, etc.)")
+    sys.exit(1)
+
+import click
+
+from src.__version__ import __repository__, __version__
+
+
+def print_header():
+    """Print the application header."""
+    click.echo(f"RemarkableSync v{__version__} by Jeff Steinbok")
+    click.echo(f"Repository: {__repository__}")
+    click.echo()
+
+
+def version_callback(ctx, param, value):
+    """Display version information."""
+    if not value or ctx.resilient_parsing:
+        return
+    print_header()
+    ctx.exit()
+
+
+@click.group(invoke_without_command=False)
+@click.option('--version', is_flag=True, callback=version_callback,
+              expose_value=False, is_eager=True,
+              help='Show version and repository information')
+@click.pass_context
+def cli(ctx):
+    """RemarkableSync - Backup and convert ReMarkable tablet files.
+
+    A unified tool to backup your ReMarkable tablet via USB and convert
+    notebooks to PDF format with template support.
+    """
+    # Print header for all commands (unless it's --version which handles it itself)
+    if ctx.invoked_subcommand and not ctx.resilient_parsing:
+        print_header()
+
+
+@cli.command()
+@click.option('--backup-dir', '-d', type=click.Path(path_type=Path),
+              default=Path('./remarkable_backup'),
+              help='Directory to store backup files')
+@click.option('--password', '-p', type=str, help='ReMarkable SSH password')
+@click.option('--verbose', '-v', is_flag=True, help='Enable verbose logging')
+@click.option('--skip-templates', is_flag=True, help='Skip backing up template files')
+@click.option('--force', '-f', is_flag=True, help='Force backup all files (ignore sync status)')
+def backup(backup_dir: Path, password: Optional[str], verbose: bool, skip_templates: bool, force: bool):
+    """Backup files from ReMarkable tablet via USB.
+
+    Connects to your ReMarkable tablet and backs up all files with incremental sync.
+    Template files are backed up by default unless --skip-templates is specified.
+    """
+    from src.commands.backup_command import run_backup_command
+    sys.exit(run_backup_command(backup_dir, password, verbose, skip_templates, force))
+
+
+@cli.command()
+@click.option('--backup-dir', '-d', type=click.Path(path_type=Path),
+              default=Path('./remarkable_backup'),
+              help='Directory containing ReMarkable backup files')
+@click.option('--output-dir', '-o', type=click.Path(path_type=Path),
+              help='Directory to save PDF files (default: backup_dir/pdfs_final)')
+@click.option('--verbose', '-v', is_flag=True, help='Enable verbose logging')
+@click.option('--force-all', '-f', is_flag=True, help='Convert all notebooks (ignore sync status)')
+@click.option('--sample', '-s', type=int, help='Convert only first N notebooks (for testing)')
+@click.option('--notebook', '-n', type=str, help='Convert only this notebook (by UUID or name)')
+def convert(backup_dir: Path, output_dir: Optional[Path], verbose: bool, force_all: bool,
+           sample: Optional[int], notebook: Optional[str]):
+    """Convert backed up notebooks to PDF format.
+
+    Converts ReMarkable notebooks to PDF with template backgrounds.
+    By default, only converts notebooks that were updated in the last backup.
+    """
+    from src.commands.convert_command import run_convert_command
+    sys.exit(run_convert_command(backup_dir, output_dir, verbose, force_all, sample, notebook))
+
+
+@cli.command()
+@click.option('--backup-dir', '-d', type=click.Path(path_type=Path),
+              default=Path('./remarkable_backup'),
+              help='Directory to store backup files')
+@click.option('--password', '-p', type=str, help='ReMarkable SSH password')
+@click.option('--verbose', '-v', is_flag=True, help='Enable verbose logging')
+@click.option('--skip-templates', is_flag=True, help='Skip backing up template files')
+@click.option('--force-backup', is_flag=True, help='Force backup all files')
+@click.option('--force-convert', is_flag=True, help='Force convert all notebooks')
+def sync(backup_dir: Path, password: Optional[str], verbose: bool, skip_templates: bool,
+        force_backup: bool, force_convert: bool):
+    """Backup and convert in one command (default workflow).
+
+    This is the most common use case: backup your tablet and then convert
+    any notebooks that were updated during the backup.
+    """
+    from src.commands.sync_command import run_sync_command
+    sys.exit(run_sync_command(backup_dir, password, verbose, skip_templates,
+                             force_backup, force_convert))
+
+
+def main():
+    """Entry point for the application."""
+    # If no command specified, default to 'sync'
+    if len(sys.argv) == 1:
+        sys.argv.append('sync')
+    cli()
+
+
+if __name__ == "__main__":
+    main()

remarkablesync-1.0.6.dist-info/METADATA

@@ -0,0 +1,384 @@
+Metadata-Version: 2.4
+Name: remarkablesync
+Version: 1.0.6
+Summary: Backup and convert reMarkable tablet notebooks to PDF
+Home-page: https://github.com/JeffSteinbok/RemarkableSync
+Author: Jeff Steinbok
+Author-email: 
+License: MIT
+Keywords: remarkable tablet backup pdf converter
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: paramiko>=3.0.0
+Requires-Dist: scp>=0.14.5
+Requires-Dist: requests>=2.31.0
+Requires-Dist: tqdm>=4.66.0
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: click>=8.1.0
+Requires-Dist: pathlib2>=2.3.7
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: PyPDF2>=3.0.0
+Requires-Dist: svglib>=1.5.0
+Requires-Dist: reportlab>=4.0.0
+Requires-Dist: keyring>=24.0.0
+Requires-Dist: rmc>=0.3.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# RemarkableSync
+[![PyPI version](https://badge.fury.io/py/remarkablesync.svg)](https://badge.fury.io/py/remarkablesync)
+[![GitHub](https://img.shields.io/badge/GitHub-RemarkableSync-blue?logo=github)](https://github.com/JeffSteinbok/RemarkableSync)
+[![CI](https://github.com/JeffSteinbok/RemarkableSync/actions/workflows/ci.yml/badge.svg)](https://github.com/JeffSteinbok/RemarkableSync/actions/workflows/ci.yml)
+[![Build Executables](https://github.com/JeffSteinbok/RemarkableSync/actions/workflows/build-executables.yml/badge.svg)](https://github.com/JeffSteinbok/RemarkableSync/actions/workflows/build-executables.yml)
+[![Release](https://github.com/JeffSteinbok/RemarkableSync/actions/workflows/release.yml/badge.svg)](https://github.com/JeffSteinbok/RemarkableSync/actions/workflows/release.yml)
+
+A comprehensive Python toolkit for backing up and converting reMarkable tablet notebooks to PDF with template support and proper folder hierarchy preservation.
+
+> [!IMPORTANT]
+> This tool has been tested exclusively on reMarkable 2. Compatibility with reMarkable 1 is not guaranteed.
+
+
+## Features
+
+### 🔄 Backup & Sync
+- **USB Connection**: Connects to reMarkable tablet over USB (10.11.99.1)
+- **Incremental Sync**: Only downloads files that have changed since last backup
+- **Complete Backup**: Backs up all notebooks, documents, and metadata
+- **Template Support**: Automatically backs up template files from the device
+- **File Integrity**: MD5 hash verification for synced files
+
+### 📄 PDF Conversion
+- **Hybrid Converter**: Supports both v5 and v6 .rm file formats
+- **Template Rendering**: Applies original notebook templates (grids, lines, etc.) to PDFs
+- **SVG Pipeline**: Uses rmc → SVG → PDF conversion for high quality output
+- **Folder Hierarchy**: Recreates original device folder structure in output
+- **Single PDF per Notebook**: Merges all pages into one PDF file per notebook
+- **Smart Conversion**: Only converts notebooks updated in the last backup
+- **Progress Tracking**: Visual progress bars and detailed logging
+
+## Prerequisites
+
+1. **reMarkable Tablet Setup**:
+   - Connect your reMarkable tablet to your computer via USB
+   - Enable SSH access (it's enabled by default)
+   - Get your SSH password from Settings → Help → Copyright and licenses
+
+2. **Python Requirements**:
+   - Python 3.11 or higher (required)
+   - Required packages (install with `pip install -r requirements.txt`)
+
+3. **External Tools** (for v6 PDF conversion):
+   - `rmc` (reMarkable file converter) - Install from https://github.com/ricklupton/rmc
+   - Note: rmc is a Rust tool, not a Python package. Install via cargo or download binaries.
+
+## Installation
+
+### Option 1: Homebrew (Recommended for macOS)
+
+**macOS users** can install RemarkableSync using Homebrew:
+
+```bash
+# Add the tap (one time only)
+brew tap jeffsteinbok/remarkablesync
+
+# Install RemarkableSync
+brew install remarkablesync
+```
+
+This will automatically:
+- Install Python 3.13 and all dependencies
+- Install the `rmc` tool for v6 format conversion
+- Set up everything needed for PDF conversion
+
+**Updating to latest version:**
+```bash
+brew upgrade remarkablesync
+```
+
+**Uninstalling:**
+```bash
+brew uninstall remarkablesync
+brew untap jeffsteinbok/remarkablesync
+```
+
+### Option 2: pip (All Platforms)
+
+**For users with Python 3.11+** installed:
+
+```bash
+# Install using pip (recommended: use a virtual environment)
+pip install remarkablesync
+
+# Then install rmc separately
+pip install rmc
+```
+
+**Using a virtual environment** (recommended):
+```bash
+# Create virtual environment
+python -m venv venv
+
+# Activate it
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install RemarkableSync
+pip install remarkablesync
+```
+
+**Updating to latest version:**
+```bash
+pip install --upgrade remarkablesync
+```
+
+### Option 3: Pre-built Executables (Windows/macOS)
+
+**For users without Python** or who prefer standalone executables:
+
+1. Download the latest release from the [Releases page](https://github.com/JeffSteinbok/RemarkableSync/releases)
+2. Extract the archive:
+   - **Windows**: Extract `RemarkableSync-Windows.zip`
+   - **macOS**: Extract `RemarkableSync-macOS.zip`
+3. Run the executable:
+   - **Windows**: `RemarkableSync.exe`
+   - **macOS**: `./RemarkableSync/RemarkableSync`
+
+For detailed instructions on building executables yourself, see [BUILD_EXECUTABLES.md](BUILD_EXECUTABLES.md).
+
+### Option 4: From Source (For Developers)
+
+1. Clone this repository:
+   ```bash
+   git clone https://github.com/JeffSteinbok/RemarkableSync.git
+   cd RemarkableSync
+   ```
+
+2. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+## Quick Start
+
+The simplest way to get started:
+
+1. **Connect your reMarkable tablet** via USB
+2. **Get your SSH password** from Settings → Help → Copyright and licenses on your tablet
+3. **Run RemarkableSync**:
+   ```bash
+   # If installed via Homebrew (macOS)
+   RemarkableSync
+
+   # If using pre-built executable
+   ./RemarkableSync
+
+   # If using Python
+   python3 RemarkableSync.py
+   ```
+4. Enter your password when prompted (you can save it for future use)
+5. Your notebooks will be backed up to `./remarkable_backup/Notebooks/`
+6. PDFs will be created in `./remarkable_backup/PDF/`
+
+That's it! The tool will only sync changed files and convert updated notebooks on subsequent runs.
+
+## Usage
+
+### Unified Command Line Interface
+
+RemarkableSync provides a single entry point with three main commands:
+
+#### Default Command: Sync (Backup + Convert)
+
+The most common workflow - backs up your device and converts only updated notebooks:
+
+```bash
+# If installed via Homebrew
+RemarkableSync
+
+# If using pre-built executable
+./RemarkableSync
+
+# If using Python
+python3 RemarkableSync.py
+```
+
+This will:
+1. Connect to your ReMarkable tablet via USB
+2. Backup all changed files (including templates)
+3. Convert only notebooks that were updated in this backup
+
+#### Individual Commands
+
+**Backup only** (no conversion):
+```bash
+# Homebrew
+RemarkableSync backup
+
+# Python
+python3 RemarkableSync.py backup
+```
+
+**Convert only** (from existing backup):
+```bash
+# Homebrew
+RemarkableSync convert
+
+# Python
+python3 RemarkableSync.py convert
+```
+
+**Sync with options**:
+```bash
+# Force full backup and conversion (ignore sync status)
+RemarkableSync sync --force-backup --force-convert
+
+# Skip template backup
+RemarkableSync sync --skip-templates
+
+# Verbose output
+RemarkableSync sync -v
+```
+
+#### Testing and Selective Conversion
+
+**Convert a single notebook** (by name or UUID):
+```bash
+RemarkableSync convert --notebook "My Notebook"
+```
+
+**Convert first N notebooks** (for testing):
+```bash
+RemarkableSync convert --sample 5
+```
+
+**Force convert all notebooks** (ignore sync status):
+```bash
+RemarkableSync convert --force-all
+```
+
+### Command Line Options
+
+**Common Options** (all commands):
+- `-d, --backup-dir`: Directory for backups (default: `./remarkable_backup`)
+- `-v, --verbose`: Enable debug logging
+- `--version`: Show version and repository information
+
+**Backup/Sync Options**:
+- `-p, --password`: ReMarkable SSH password (will prompt if not provided)
+- `--skip-templates`: Don't backup template files
+- `-f, --force` / `--force-backup`: Backup all files (ignore sync status)
+
+**Convert Options**:
+- `-o, --output-dir`: Output directory for PDFs (default: `backup_dir/pdfs_final`)
+- `-f, --force-all` / `--force-convert`: Convert all notebooks (ignore sync status)
+- `-s, --sample N`: Convert only first N notebooks
+- `-n, --notebook NAME`: Convert only specific notebook (by UUID or name)
+
+## How It Works
+
+1. **Connection**: Establishes SSH connection to ReMarkable tablet at 10.11.99.1
+2. **File Discovery**: Scans `/home/root/.local/share/remarkable/xochitl/` for notebook files
+3. **Template Backup**: Downloads template files from `/usr/share/remarkable/templates/`
+4. **Incremental Sync**: Compares file metadata (size, modification time, hash) to determine what needs updating
+5. **Download**: Uses SCP to efficiently transfer only changed files
+6. **PDF Conversion**:
+   - Converts .rm files to SVG using rmc (for v6 format)
+   - Renders template backgrounds (grids, lines, dots)
+   - Merges templates with notebook content
+   - Combines all pages into single PDF per notebook
+7. **Smart Updates**: Tracks which notebooks changed and only converts those
+
+## File Structure
+
+After backup, your directory will contain three clean folders:
+
+```
+remarkable_backup/
+├── Notebooks/                # All notebook files and metadata
+│   ├── [uuid].metadata       # Document metadata files
+│   ├── [uuid].content        # Document content info
+│   └── [uuid]/               # Notebook directories
+│       ├── [uuid]-metadata.json  # Page metadata
+│       └── *.rm              # Drawing/writing data (v5 or v6 format)
+├── Templates/                # Template files from device
+│   ├── *.png                 # Template preview images
+│   ├── *.template            # Template definition files
+│   └── templates.json        # Template metadata
+├── PDF/                      # Generated PDF outputs
+│   └── [notebook folders with PDFs preserving hierarchy]
+├── sync_metadata.json        # Sync state tracking
+├── updated_notebooks.txt     # List of notebooks updated in last backup
+└── .remarkable_backup.log    # Backup operation log
+```
+
+## PDF Conversion Technical Details
+
+RemarkableSync includes a hybrid converter that supports both v5 and v6 .rm file formats:
+
+- **v6 Format** (newer tablets): Uses external `rmc` tool to convert .rm → SVG → PDF
+- **v5 Format** (older tablets): Direct Python-based conversion (legacy support)
+- **Template Rendering**: Custom renderer applies original device templates with accurate scaling (226 DPI → 72 DPI PDF points)
+- **Page Merging**: Uses PyPDF2 to composite template backgrounds with notebook content
+
+### External Tool: rmc
+
+For v6 notebook conversion, you'll need the `rmc` tool:
+- **Repository**: https://github.com/ricklupton/rmc
+- **Installation**: Via Rust cargo or download pre-built binaries
+- **Note**: This is NOT a Python package - install separately
+
+## Incremental Sync Details
+
+The tool maintains a `sync_metadata.json` file that tracks:
+- File modification times
+- File sizes  
+- MD5 hashes of local files
+- Last sync timestamps
+
+Files are only downloaded if:
+- They don't exist locally
+- Remote modification time changed
+- Remote file size changed
+- Local file hash doesn't match stored hash
+
+## Troubleshooting
+
+### Connection Issues
+- Ensure ReMarkable is connected via USB
+- Verify the tablet shows up as network interface
+- Try pinging `10.11.99.1`
+- Check SSH password from tablet settings
+
+### Permission Errors
+- Run as administrator on Windows if needed
+- Ensure backup directory is writable
+
+### File Access Issues
+- Restart ReMarkable tablet if SSH becomes unresponsive
+- Check available disk space on both devices
+
+## Security Notes
+
+- SSH password is requested interactively (not stored)
+- Uses paramiko with auto-add host key policy
+- Files are transferred over local USB network (not internet)
+
+## License
+
+This tool is for personal use with your own ReMarkable tablet. Respect ReMarkable's terms of service.

remarkablesync-1.0.6.dist-info/RECORD

@@ -0,0 +1,26 @@
+RemarkableSync.py,sha256=Ls3foJQbpFjxyIj-Jk23GN1XWI10VRf9URhmLlYc_SY,5338
+src/__init__.py,sha256=zrN0c456h8aQaXEAN7wuFwyT1XyOB4Xt-hSOq97B0aM,144
+src/__version__.py,sha256=_rkizXc4E1nHX9PV75XMyqHnoQvUQixwalbAiI3Mp3U,135
+src/converter.py,sha256=JRpyI05-dEiXLoEMp2xUJHIoH2Fj47InLuVuFXkMitc,4436
+src/hybrid_converter.py,sha256=S-m6uuvpkoJB8bfz7KcyeQzO6KExpZHLmfV0fJ5QZHc,25724
+src/template_renderer.py,sha256=NYGvFFLUtbQO_x0zG15MSh4xQNvg1CN5VHgS_vmHb0E,9967
+src/backup/__init__.py,sha256=OavqHlWvXQeREmKS91Mxs6Z9aOdNRuFXBjTdUtFh9qs,429
+src/backup/backup_manager.py,sha256=8sozxG8VhktOJhoBa0Gag3KDon_ZfXXLuVqlcc6hm4A,16515
+src/backup/connection.py,sha256=UGreP_uIyIj9u20yJrimQL4hAAcbRADa7AClRj3u4Vc,11876
+src/backup/metadata.py,sha256=8hTsHQGhuxndMDrmv2bWTwJtUEWf9CTtAUfqeD59mQo,4479
+src/commands/__init__.py,sha256=hZBGHSue4lDZgeXVJU0T8BDSgd4PaXtQmDtjMe9mZSE,54
+src/commands/backup_command.py,sha256=UD39U_422hkoY4rjEcw8ZSiPf_BzV_G4_wlb_e5zOvg,1942
+src/commands/convert_command.py,sha256=wWTFUkJ86xRZHEGQROzLniai5qYPa6f1kuivyljwmjA,2431
+src/commands/sync_command.py,sha256=XyySgAA-mpj7zXHgcH2ZDBDJwosmYrVsyuUHlfg0YkM,2399
+src/converters/__init__.py,sha256=MX4I6N2ZfdKfhYNJlUJlH4Pows2rAy30Ay4anrasnOY,427
+src/converters/base_converter.py,sha256=Y8uzFyB0SfmahZy-1qa-3BtxZk8YD9RJcjzPX6kV4YI,7577
+src/converters/v4_converter.py,sha256=OMpyqCQ6dhKqQlOUXbZh5YVZ3Bu8in7867Kav9Y7z_k,5759
+src/converters/v5_converter.py,sha256=rCRGGG7apNldIntHj8QVJYYusg0fbwW2JbEoIsJfres,6244
+src/converters/v6_converter.py,sha256=tujxRcalL4Csf6otbx6mBLadDqg8NMn6uh2kSMhw9jM,4836
+src/utils/__init__.py,sha256=py_WhGWa0gg4PEny3qpoi1iJ_grtEARQfwIIsH1RQh4,42
+src/utils/logging.py,sha256=q8CHFvZj4IcDPTogC5vRdqEOHLPNEB9fgLYhlDwsOBQ,792
+remarkablesync-1.0.6.dist-info/METADATA,sha256=9-mHDOLFtzU3tGLRToGrFyPbUKqoAl4puMA9hP7kmoE,12628
+remarkablesync-1.0.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+remarkablesync-1.0.6.dist-info/entry_points.txt,sha256=ue6T2_WgcJinQTpeI7fJ1MvdxeN6o7KX23oQN3-8VT4,55
+remarkablesync-1.0.6.dist-info/top_level.txt,sha256=IEGt96lB3NxnvDEmPR4DcurlQYD2EHEn2pzAUJdq7sY,19
+remarkablesync-1.0.6.dist-info/RECORD,,

remarkablesync-1.0.6.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

remarkablesync-1.0.6.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+RemarkableSync = RemarkableSync:main

remarkablesync-1.0.6.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+RemarkableSync
+src

src/__init__.py

@@ -0,0 +1,5 @@
+"""ReMarkable Backup Tool - Main package."""
+
+from .__version__ import __repository__, __version__
+
+__all__ = ["__version__", "__repository__"]

src/__version__.py

@@ -0,0 +1,4 @@
+"""Version information for RemarkableSync."""
+
+__version__ = "1.0.6"
+__repository__ = "https://github.com/JeffSteinbok/RemarkableSync"

src/backup/__init__.py

@@ -0,0 +1,12 @@
+"""
+Backup package for ReMarkable tablet backup functionality.
+
+This package provides modular components for backing up ReMarkable tablets,
+including SSH connection management, file metadata handling, and backup orchestration.
+"""
+
+from .backup_manager import ReMarkableBackup
+from .connection import ReMarkableConnection
+from .metadata import FileMetadata
+
+__all__ = ["ReMarkableConnection", "FileMetadata", "ReMarkableBackup"]