doctopdf 2.0.5b0__py3-none-any.whl

doctopdf/__init__.py

@@ -0,0 +1,10 @@
+"""
+doctopdf — macOS batch document converter using Microsoft Word.
+
+Converts .doc and .docx files to PDF via AppleScript/JXA automation of
+Microsoft Word. Runs entirely offline with no cloud dependencies.
+"""
+
+__version__ = '2.0.5-beta'
+__author__ = 'DocToPDF Team'
+__description__ = 'Offline batch .doc/.docx → PDF converter using Microsoft Word on macOS'

doctopdf/__main__.py

@@ -0,0 +1,13 @@
+#!/usr/bin/env python3
+"""
+Entry point for `python -m doctopdf`.
+
+Allows running the converter as a module:
+    python -m doctopdf --input ./docs --output ./pdfs
+"""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

doctopdf/applescript/check_word.applescript

@@ -0,0 +1,19 @@
+(*
+ check_word.applescript — Probe for Microsoft Word installation.
+
+ Returns JSON to stdout indicating whether Word is installed and
+ scriptable via AppleScript/JXA.
+
+ Output:
+   {"installed": true, "version": "16.72"}
+   {"installed": false, "error": "…"}
+*)
+
+try
+    tell application "Microsoft Word"
+        set ver to version
+    end tell
+    return "{\"installed\":true,\"version\":\"" & ver & "\"}"
+on error errMsg
+    return "{\"installed\":false,\"error\":\"" & errMsg & "\"}"
+end try

doctopdf/applescript/export_document.applescript

@@ -0,0 +1,116 @@
+(*
+ export_document.applescript — Bridge between Python orchestrator and Microsoft Word.
+
+ Opens a document file in Microsoft Word on macOS, exports it as PDF,
+ and closes the document without saving changes to the original.
+
+ Usage via osascript:
+   osascript export_document.applescript "<inputPath>" "<outputPath>" [timeoutSec]
+
+ Output (stdout):
+   {"status":"success","input":"...","output":"..."}
+   {"status":"error","input":"...","error":"..."}
+
+ Returns JSON to stdout so the Python orchestrator can parse results reliably.
+
+ Note: Paths must be absolute POSIX paths. The script converts them to
+ Alias objects for Word using `POSIX file as alias` coercion.
+*)
+
+on run argv
+    -- ── Parse arguments ────────────────────────────────────────
+    if (count of argv) < 2 then
+        return "{\"status\":\"error\",\"error\":\"Missing arguments. Usage: export_document.applescript <inputPath> <outputPath> [timeoutSec]\"}"
+    end if
+
+    set inputPath to item 1 of argv
+    set outputPath to item 2 of argv
+
+    -- ── Validate input file exists ─────────────────────────────
+    try
+        set inputFile to inputPath as POSIX file as alias
+    on error
+        return "{\"status\":\"error\",\"input\":\"" & inputPath & "\",\"error\":\"File not found: " & inputPath & "\"}"
+    end try
+
+    -- ── Convert ────────────────────────────────────────────────
+    try
+        tell application "Microsoft Word"
+            -- Open the document
+            open inputFile
+
+            -- Wait briefly for Word to finish loading the document.
+            -- The document may not be immediately scriptable after open().
+            delay 1
+
+            -- Capture a stable reference to the document before exporting.
+            -- After save-as, active document may change, so we hold a
+            -- persistent reference here.
+            set targetDoc to active document
+            if targetDoc is missing value then
+                -- File needs more time to load
+                delay 2
+                set targetDoc to active document
+            end if
+
+            -- Export as PDF using Word's built-in PDF format constant
+            save as targetDoc file name outputPath file format format PDF
+
+            -- Close the document without saving changes to the original.
+            -- We use the captured reference rather than 'active document'
+            -- because after save-as the active document may have shifted.
+            try
+                close targetDoc saving no
+            on error
+                -- If the captured reference is stale, try active document
+                try
+                    close active document saving no
+                end try
+                -- If both fail, the document may have auto-closed after save.
+                -- This is not a conversion failure — the PDF was already created.
+            end try
+        end tell
+
+        -- ── Verify output was created ──────────────────────────
+        try
+            set outputFile to outputPath as POSIX file as alias
+            return "{\"status\":\"success\",\"input\":\"" & inputPath & "\",\"output\":\"" & outputPath & "\"}"
+        on error
+            return "{\"status\":\"error\",\"input\":\"" & inputPath & "\",\"error\":\"PDF file was not created at: " & outputPath & "\"}"
+        end try
+
+    on error errMsg
+        -- ── Cleanup ────────────────────────────────────────────
+        -- Attempt to close any open document without saving
+        try
+            tell application "Microsoft Word"
+                close active document saving no
+            end tell
+        end try
+
+        -- Check for common permission error
+        if errMsg contains "-1743" then
+            return "{\"status\":\"error\",\"input\":\"" & inputPath & "\",\"error\":\"macOS Automation permission denied (-1743). Grant Terminal access to control Microsoft Word in System Settings → Privacy & Security → Automation.\"}"
+        end if
+
+        -- Escape quotes in the error message for JSON
+        set escapedMsg to my escape_json(errMsg)
+        return "{\"status\":\"error\",\"input\":\"" & inputPath & "\",\"error\":\"" & escapedMsg & "\"}"
+    end try
+end run
+
+-- Helper: escape special characters for JSON output
+on escape_json(str)
+    set AppleScript's text item delimiters to "\\"
+    set str to text items of str
+    set AppleScript's text item delimiters to "\\\\"
+    set str to str as string
+
+    set AppleScript's text item delimiters to "\""
+    set str to text items of str
+    set AppleScript's text item delimiters to "\\\""
+    set str to str as string
+
+    set AppleScript's text item delimiters to ""
+    return str
+end escape_json

doctopdf/applescript/export_document.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env osascript -l JavaScript
+/**
+ * export_document.js — JXA bridge to Microsoft Word
+ *
+ * Opens a document in Microsoft Word on macOS and exports it as PDF.
+ * Returns a JSON-encoded result object to stdout so the Python
+ * orchestrator can parse it reliably.
+ *
+ * Usage (via osascript):
+ *   osascript -l JavaScript export_document.js <inputPath> <outputPath> [timeoutSec]
+ *
+ * Output (stdout):
+ *   {"status":"success","input":"...","output":"..."}
+ *   {"status":"error","input":"...","error":"..."}
+ *
+ * Exit codes:
+ *   0 — JSON result written to stdout (check "status" key)
+ *   1 — osascript-level failure (script error, not Word error)
+ */
+
+function run(argv) {
+    // ── Parse arguments ────────────────────────────────────────
+    if (argv.length < 2) {
+        return JSON.stringify({
+            status: 'error',
+            error: 'Missing arguments. Usage: export_document.js <inputPath> <outputPath> [timeoutSec]'
+        });
+    }
+
+    var inputPath  = String(argv[0]);
+    var outputPath = String(argv[1]);
+    var timeoutSec = argv.length > 2 ? parseInt(argv[2], 10) : 60;
+
+    if (isNaN(timeoutSec) || timeoutSec < 1) {
+        timeoutSec = 60;
+    }
+
+    // ── Validate file exists ───────────────────────────────────
+    var fm = $.NSFileManager.defaultManager;
+    if (!fm.fileExistsAtPath(inputPath)) {
+        return JSON.stringify({
+            status: 'error',
+            input: inputPath,
+            error: 'File not found: ' + inputPath
+        });
+    }
+
+    // ── Perform conversion ─────────────────────────────────────
+    try {
+        var app = Application('Microsoft Word');
+        app.includeStandardAdditions = true;
+
+        // -- Open the document -----------------------------------
+        var doc = app.open(inputPath);
+        if (!doc) {
+            return JSON.stringify({
+                status: 'error',
+                input: inputPath,
+                error: 'Word returned null when opening document'
+            });
+        }
+
+        // -- Export as PDF ---------------------------------------
+        // The 'as' parameter value may vary by Word locale/version.
+        // Common values: 'PDF', 'Microsoft Word Document (*.pdf)', or
+        // internal constant. We default to 'PDF'.
+        var exportResult = doc.export({
+            to: outputPath,
+            as: 'PDF'
+        });
+
+        // -- Close without saving changes to original ------------
+        doc.close({ saving: 'no' });
+
+        // -- Verify output was created ---------------------------
+        if (!fm.fileExistsAtPath(outputPath)) {
+            return JSON.stringify({
+                status: 'error',
+                input: inputPath,
+                error: 'Word reported success but PDF was not created at: ' + outputPath
+            });
+        }
+
+        return JSON.stringify({
+            status: 'success',
+            input: inputPath,
+            output: outputPath
+        });
+
+    } catch (e) {
+        // ── Cleanup ────────────────────────────────────────────
+        // Attempt to close any document that may still be open.
+        try {
+            var activeDoc = app.activeDocument;
+            if (activeDoc) {
+                activeDoc.close({ saving: 'no' });
+            }
+        } catch (ignore) {
+            // Best-effort cleanup; ignore further errors.
+        }
+
+        var errorMsg = String(e.message || e);
+        // Detect common macOS permission error
+        if (errorMsg.indexOf('-1743') !== -1) {
+            errorMsg = 'macOS Automation permission denied (-1743). ' +
+                'Grant Terminal/automation access to control Microsoft Word.';
+        } else if (errorMsg.indexOf('Microsoft Word') === -1 && errorMsg.indexOf('Error') === -1) {
+            // Some JXA errors omit the app name — prefix for clarity
+            errorMsg = 'Microsoft Word: ' + errorMsg;
+        }
+
+        return JSON.stringify({
+            status: 'error',
+            input: inputPath,
+            error: errorMsg,
+            suggestions: [
+                'Ensure the document is not already open in Word',
+                'Ensure the output path is writable',
+                'Check the document is not corrupt'
+            ]
+        });
+    }
+}

doctopdf/cli.py

@@ -0,0 +1,295 @@
+#!/usr/bin/env python3
+"""
+CLI module — command-line interface for DocToPDF.
+
+Provides argument parsing and dispatches to the orchestrator.
+Supports both standard CLI usage and Automator Quick Action invocation.
+
+Usage:
+    convert-word-pdf --input ./docs --output ./pdfs
+    convert-word-pdf --input ./docs --output ./pdfs --recursive --flat
+    convert-word-pdf --check
+    convert-word-pdf --input ./docs --output ./pdfs --dry-run
+    convert-word-pdf --version
+"""
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from . import __version__
+from .orchestrator import Orchestrator
+from .converter import WordConverter
+from .errors import WordNotInstalledError, WordPermissionError, FileAccessError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the argument parser with all CLI options."""
+    parser = argparse.ArgumentParser(
+        prog='convert-word-pdf',
+        description=(
+            'Batch convert .doc and .docx files to PDF using Microsoft Word. '
+            'Runs entirely offline with no cloud dependencies.'
+        ),
+        epilog=(
+            'Examples:\n'
+            '  %(prog)s --input ./docs --output ./pdfs\n'
+            '  %(prog)s --input ./docs --output ./pdfs --recursive --flat\n'
+            '  %(prog)s --check\n'
+            '  %(prog)s --input ./docs --output ./pdfs --dry-run\n'
+            '\n'
+            'Requires Microsoft Word for macOS. Automator Quick Action:\n'
+            '  See README.md for Finder right-click integration.'
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    # ── Required (or alternative) ───────────────────────────────
+    parser.add_argument(
+        '--input', '-i',
+        type=Path,
+        metavar='DIR',
+        help='Input directory containing .doc/.docx files',
+    )
+    parser.add_argument(
+        '--output', '-o',
+        type=Path,
+        metavar='DIR',
+        help='Output directory for generated PDF files',
+    )
+
+    # ── Scanning options ────────────────────────────────────────
+    parser.add_argument(
+        '--recursive', '-r',
+        action='store_true',
+        default=True,
+        help='Recursively scan input subdirectories (default: on)',
+    )
+    parser.add_argument(
+        '--no-recursive',
+        action='store_false',
+        dest='recursive',
+        help='Do not scan subdirectories (top-level only)',
+    )
+    parser.add_argument(
+        '--flat',
+        action='store_true',
+        default=False,
+        help=(
+            'Write all PDFs flat into output directory instead of '
+            'mirroring the input folder structure'
+        ),
+    )
+
+    # ── Conversion options ──────────────────────────────────────
+    parser.add_argument(
+        '--timeout',
+        type=int,
+        default=60,
+        metavar='SEC',
+        help='Seconds to wait per document before timing out (default: 60)',
+    )
+    parser.add_argument(
+        '--retry',
+        type=int,
+        default=2,
+        metavar='N',
+        help='Number of retries per failed conversion (default: 2)',
+    )
+    parser.add_argument(
+        '--restart-every',
+        type=int,
+        default=10,
+        metavar='N',
+        help='Restart Word after N successful conversions (0 = never restart, '
+             'the default). Useful to prevent state degradation in very large '
+             'batches (100+ files).',
+    )
+
+    # ── Output options ──────────────────────────────────────────
+    parser.add_argument(
+        '--dry-run', '-n',
+        action='store_true',
+        help='Scan and report files without performing conversion',
+    )
+    parser.add_argument(
+        '--log-file',
+        type=Path,
+        metavar='FILE',
+        help='Write structured log to FILE (.json or .csv)',
+    )
+    parser.add_argument(
+        '--quiet', '-q',
+        action='store_true',
+        help='Suppress per-file status output (summary only)',
+    )
+
+    # ── Utility ─────────────────────────────────────────────────
+    parser.add_argument(
+        '--verbose',
+        action='store_true',
+        help='Enable verbose debug logging (shows internal Word cleanup/restart diagnostics)',
+    )
+    parser.add_argument(
+        '--check',
+        action='store_true',
+        help='Check if Microsoft Word is installed and scriptable, then exit',
+    )
+    parser.add_argument(
+        '--version', '-v',
+        action='version',
+        version=f'%(prog)s {__version__}',
+        help='Show version number and exit',
+    )
+
+    return parser
+
+
+def _configure_logging(verbose: bool) -> None:
+    """Configure stdlib logging: warnings visible by default, debug with --verbose."""
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.WARNING,
+        format='%(levelname)s %(name)s: %(message)s',
+        stream=sys.stderr,
+    )
+
+
+def cmd_check() -> int:
+    """Probe for Microsoft Word and report status."""
+    installed, info = WordConverter.check_word_installed()
+
+    if installed:
+        print(f'✓ Microsoft Word is installed (version: {info})')
+        print('  The automation bridge is operational.')
+        return 0
+    else:
+        print('✗ Microsoft Word is NOT installed or not scriptable.')
+        print()
+        print('  To use this tool, install Microsoft Word for macOS:')
+        print('    - Microsoft 365 (subscription)')
+        print('    - Microsoft Office 2019 or later (one-time purchase)')
+        print()
+        print('  After installing Word, grant Automation permissions:')
+        print('    System Settings → Privacy & Security → Automation')
+        print('    → Allow Terminal (or your app) to control "Microsoft Word"')
+        print()
+        print(f'  Probe details: {info}')
+        return 1
+
+
+def cmd_validate_args(args: argparse.Namespace) -> Optional[str]:
+    """Validate mutually-dependent arguments. Returns error string or None."""
+    if not args.input and not args.check:
+        return '--input is required (use --check to probe for Word)'
+
+    if args.input and not args.input.is_dir():
+        return f'Input path is not a directory or does not exist: {args.input}'
+
+    if not args.output and not args.check and not args.dry_run:
+        # In dry-run mode, output is not strictly needed
+        if args.input:
+            return '--output is required for conversion (omit with --dry-run)'
+
+    if args.log_file:
+        parent = Path(args.log_file).parent
+        if not parent.exists():
+            try:
+                parent.mkdir(parents=True, exist_ok=True)
+            except PermissionError:
+                return f'Cannot create directory for log file: {args.log_file}'
+
+    return None
+
+
+def cmd_convert(args: argparse.Namespace) -> int:
+    """Run the batch conversion."""
+    # If no --output was given but we have --input, use a default
+    output_dir = args.output
+    if not output_dir and args.input:
+        output_dir = Path.home() / 'Documents' / 'PDF_Conversions'
+        print(f'  Output directory not specified, using: {output_dir}')
+
+    orchestrator = Orchestrator(
+        input_dir=args.input,
+        output_dir=output_dir,
+        recursive=args.recursive,
+        flat=args.flat,
+        timeout=args.timeout,
+        retry=args.retry,
+        restart_every=args.restart_every,
+        dry_run=args.dry_run,
+        log_file=args.log_file,
+    )
+
+    try:
+        orchestrator.run()
+    except KeyboardInterrupt:
+        print('\n\nCancelled by user.')
+        return 130
+
+    success = orchestrator.success_count
+    errors = orchestrator.error_count
+
+    if orchestrator.dry_run:
+        return 0
+
+    # Print opening line if output was created
+    if success > 0:
+        print(f'\n  PDFs written to: {output_dir}')
+
+    # Return non-zero if any errors occurred
+    return 0 if errors == 0 else 1
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """
+    CLI entry point.
+
+    Args:
+        argv: Argument list (defaults to sys.argv[1:]).
+
+    Returns:
+        Exit code (0 = success, 1 = error, 130 = cancelled).
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    # Configure stdlib logging before any work; warnings show by default,
+    # debug diagnostics require --verbose.
+    _configure_logging(args.verbose)
+
+    # ── Mode dispatch ──────────────────────────────────────────
+    if args.check:
+        return cmd_check()
+
+    # ── Validate ────────────────────────────────────────────────
+    error_msg = cmd_validate_args(args)
+    if error_msg:
+        parser.error(error_msg)
+        return 2  # pragma: no cover
+
+    # ── Convert ─────────────────────────────────────────────────
+    try:
+        return cmd_convert(args)
+    except WordNotInstalledError:
+        print('ERROR: Microsoft Word is not installed or not scriptable.')
+        print('  Run with --check for diagnostic information.')
+        print('  Alternatively, install Microsoft Word for macOS.')
+        return 1
+    except WordPermissionError as e:
+        print(f'ERROR: {e}')
+        return 1
+    except FileAccessError as e:
+        print(f'ERROR: {e}')
+        return 1
+    except Exception as e:
+        print(f'ERROR: Unexpected error: {e}', file=sys.stderr)
+        import traceback
+        traceback.print_exc(file=sys.stderr)
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

doctopdf/config.py

@@ -0,0 +1,54 @@
+"""
+Configuration defaults and constants for the DocToPDF converter.
+
+Centralises all tunable parameters so they can be adjusted without
+digging through implementation modules.
+"""
+
+from pathlib import Path
+
+# ── File discovery ──────────────────────────────────────────────
+SUPPORTED_EXTENSIONS: set = {'.doc', '.docx'}
+"""File extensions treated as convertible documents (case-insensitive)."""
+
+MIN_FILE_SIZE_BYTES: int = 1
+"""Files smaller than this (in bytes) are skipped as likely empty."""
+
+# ── Conversion defaults ─────────────────────────────────────────
+DEFAULT_TIMEOUT: int = 60
+"""Seconds to wait for Word to convert a single document before timing out."""
+
+DEFAULT_RETRY_COUNT: int = 2
+"""Number of additional attempts per file after the first failure."""
+
+DEFAULT_RETRY_DELAY: float = 2.0
+"""Base seconds to wait between retries (actual = delay × attempt_number)."""
+
+# ── Output structure ────────────────────────────────────────────
+DEFAULT_OUTPUT_DIR: Path = Path.home() / 'Documents' / 'PDF_Conversions'
+"""Fallback output directory when --output is not specified."""
+
+DEFAULT_FLAT: bool = False
+"""If True, write all PDFs to a single flat output directory instead of mirrored tree."""
+
+# ── Logging ─────────────────────────────────────────────────────
+DEFAULT_LOG_FORMAT: str = 'text'
+"""One of 'text', 'json', 'csv'."""
+
+# ── Path to bundled AppleScript/JXA assets ──────────────────────
+SCRIPT_DIR: Path = Path(__file__).parent / 'applescript'
+
+APPLESCRIPT_EXPORT_SCRIPT: Path = SCRIPT_DIR / 'export_document.applescript'
+"""Primary: AppleScript that opens a document in Word and exports it as PDF."""
+
+JXA_EXPORT_SCRIPT: Path = SCRIPT_DIR / 'export_document.js'
+"""Fallback: JXA script that opens a document in Word and exports it as PDF."""
+
+APPLESCRIPT_CHECK_WORD: Path = SCRIPT_DIR / 'check_word.applescript'
+"""AppleScript that returns JSON indicating whether Word is installed."""
+
+# ── Word version support ────────────────────────────────────────
+# Some Word versions use different constant names for PDF format.
+# This is probed at runtime but can be overridden.
+WORD_FORMAT_PDF: str = 'PDF'
+"""The format identifier used in Word's export command."""