conver 0.1.0__py3-none-any.whl

conver/__init__.py

@@ -0,0 +1,25 @@
+"""
+Convenient public API for the conver package.
+"""
+
+from .conver import conver
+from .conver import ConverError
+from .conver import InputFileNotFound
+from .conver import UnsupportedFormat
+from .conver import WordStartError
+from .conver import SaveError
+from .conver import IPCError
+from .conver import PlatformNotSupported
+from .__version__ import __version__
+
+__all__ = [
+    "conver",
+    "ConverError",
+    "InputFileNotFound",
+    "UnsupportedFormat",
+    "WordStartError",
+    "SaveError",
+    "IPCError",
+    "PlatformNotSupported",
+    "__version__",
+]

conver/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

conver/_convert.py

@@ -0,0 +1,193 @@
+# Author: Timur Ulyahin, https://github.com/ucomru
+# License: MIT – provided "as-is" without any warranty or liability
+# Copyright: (c) 2024 Timur Ulyahin
+
+"""
+MODULE OVERVIEW:
+    This module implements the low-level IPC-based `convert` function used to perform
+    document format conversion by invoking platform-specific scripts for macOS (JXA)
+    and Windows (PowerShell).
+
+    It serves as the internal transport layer between Python and the operating-system
+    automation scripts, enabling the conversion of Microsoft Word documents (.doc, .docx)
+    and other supported formats into output formats such as PDF, RTF, TXT, HTML, and more.
+
+    The function returns structured information (status, message, error_code) that
+    is interpreted by the high-level `conver()` API, which converts these results
+    into Python exceptions on failure.
+
+USAGE:
+    To use the `convert` function, specify the `input_path`, `output_path`, and optionally
+    `keep_open` to indicate whether the application should remain open post-conversion.
+
+RECOMMENDED PATHS:
+    Use paths like "~/Downloads/" on macOS or "C:/Users/YourName/Downloads/" on Windows
+    for both `input_path` and `output_path` to ensure permission consistency.
+
+SETUP (macOS):
+    1. Go to System Settings > Privacy & Security > Files and Folders.
+    2. Under Microsoft Word or Microsoft Excel, enable access to "Downloads/" if required.
+
+SUPPORTED FORMATS:
+    The function supports conversion of the following file extensions:
+    - Microsoft Word (.docx)    // Modern Word document format
+    - Word 97-2003 (.doc)       // Legacy Word document format
+    - PDF (.pdf)                // Export documents to PDF format
+    - Rich Text Format (.rtf)   // Basic document format with limited formatting
+    - OpenDocument Text (.odt)  // OpenOffice/LibreOffice document format
+    - Plain Text (.txt)         // Plain text format without any formatting
+    - HTML (.html)              // Web page format for viewing in browsers
+
+STATUS SCHEMA (ConvertResult):
+    The function returns a structured dictionary as follows:
+    {
+        "status": "success" | "error",        // Execution status
+        "input": "<path to input file>",      // Path to the input file (may be null in error cases)
+        "output": "<path to output file>",    // Path to the output file (may be null in error cases)
+        "message": "OK" | "<error message>",  // "OK" on success or specific error message
+        "error_code": 0 | <error code>        // 0 for success; specific code for different errors
+    }
+
+ERROR CODES:
+    The `convert` function and associated scripts define a set of error codes for troubleshooting:
+    0   - Success
+    1   - Incorrect JSON format or missing required fields
+    2   - Input file format is unsupported
+    3   - Output file format is unsupported
+    11  - Input file not found
+    21  - Microsoft Word or Excel did not start within the expected time
+    31  - Error saving or converting file
+    98  - Invalid JSON output from script
+    99  - Unsupported platform
+"""
+
+import subprocess
+from json import loads, dumps, JSONDecodeError
+import sys
+from importlib.resources import files, as_file
+from typing import TypedDict, Optional, List
+
+
+class ConvertResult(TypedDict):
+    status: str
+    input: Optional[str]
+    output: Optional[str]
+    message: str
+    error_code: int
+
+
+def convert(
+    input_path: str, output_path: str, keep_open: bool = False
+) -> ConvertResult:
+    """
+    Convert a document from one format to another using platform-specific scripts.
+
+    This function acts as an interface for inter-process communication (IPC) with macOS
+    or Windows scripts to perform document conversions. Depending on the operating system,
+    it triggers a JXA or PowerShell script, which performs the conversion and returns a
+    structured JSON result. The `convert` function processes the JSON result, ensuring
+    it matches the strict structure defined by `ConvertResult`.
+
+    Parameters:
+        input_path (str): The path to the source file.
+        output_path (str): The path where the converted file will be saved.
+        keep_open (bool): Whether to keep the application (Word/Excel) open after processing.
+
+    Returns:
+        ConvertResult: A dictionary with keys for `status`, `input`, `output`, `message`, and
+        `error_code`, providing details of the conversion process and any errors encountered.
+
+    Errors:
+        Returns structured error responses as defined by the ConvertResult type. Unexpected errors
+        that are not captured by the script will return error_code 98 for JSON parsing failures.
+    """
+    if sys.platform == "darwin":
+        return _run_macos_script(input_path, output_path, keep_open)
+    elif sys.platform == "win32":
+        return _run_windows_script(input_path, output_path, keep_open)
+    else:
+        # Unsupported platform
+        return {
+            "status": "error",
+            "input": input_path,
+            "output": output_path,
+            "message": "Unsupported platform.",
+            "error_code": 99,
+        }
+
+
+def _run_macos_script(
+    input_path: str, output_path: str, keep_open: bool
+) -> ConvertResult:
+    """Run macOS JXA script for conversion."""
+    with as_file(files("conver.scripts").joinpath("convert.jxa")) as script_path:
+        command = [
+            "osascript",
+            "-l",
+            "JavaScript",
+            str(script_path),
+            dumps({"input": input_path, "output": output_path, "keepOpen": keep_open}),
+        ]
+        return _execute_command(command, input_path, output_path)
+
+
+def _run_windows_script(
+    input_path: str, output_path: str, keep_open: bool
+) -> ConvertResult:
+    """Run Windows PowerShell script for conversion."""
+    with as_file(files("conver.scripts").joinpath("convert.ps1")) as script_path:
+        command = [
+            "powershell",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-File",
+            str(script_path),
+            "-jsonArgs",
+            dumps({"input": input_path, "output": output_path, "keepOpen": keep_open}),
+        ]
+        return _execute_command(command, input_path, output_path)
+
+
+def _execute_command(
+    command: List[str], input_path: str, output_path: str
+) -> ConvertResult:
+    """
+    Executes the command for either macOS or Windows and parses the JSON output.
+
+    Attempts to run the provided script command and expects JSON output for successful completion.
+    In cases where the script exits with an error, the `error_code` from the script’s JSON response
+    is returned directly to help identify specific issues. If JSON parsing fails, a general error
+    code of 98 is returned.
+
+    Parameters:
+        command (List[str]): The command to be executed.
+        input_path (str): The path to the input file, passed for error context.
+        output_path (str): The path to the output file, passed for error context.
+
+    Returns:
+        ConvertResult: A structured dictionary with status, message, error code, input, and output.
+    """
+    result = subprocess.run(command, capture_output=True, text=True)
+
+    # osascript places all output in stderr, including success
+    raw = result.stdout.strip() or result.stderr.strip()
+
+    try:
+        data = loads(raw)
+    except JSONDecodeError:
+        return {
+            "status": "error",
+            "input": input_path,
+            "output": output_path,
+            "message": "Invalid JSON output from script.",
+            "error_code": 98,
+        }
+
+    # canonical normalized result
+    return {
+        "status": data.get("status", "error"),
+        "input": data.get("input", input_path),
+        "output": data.get("output", output_path),
+        "message": data.get("message", ""),
+        "error_code": data.get("error_code", result.returncode),
+    }

conver/cli.py

@@ -0,0 +1,90 @@
+import sys
+from pathlib import Path
+
+from click import (
+    command,
+    argument,
+    option,
+    version_option,
+    echo,
+    Path as ClickPath,
+    UsageError,
+)
+
+from .conver import conver, ConverError
+from .__version__ import __version__
+
+
+def fail(label: str, err: Exception, code: int = 1):
+    echo(f"{label} {err}", err=True)
+    sys.exit(code)
+
+
+@command(help="Convert Word documents.")
+@argument(
+    "inputs", type=ClickPath(exists=True, path_type=Path), nargs=-1, metavar="INPUT..."
+)
+@option(
+    "-o",
+    "--output",
+    "output",
+    type=ClickPath(path_type=Path),
+    required=False,
+    help="Output file or directory (for multiple inputs).",
+)
+@option("-p", "--pdf", "target", flag_value="pdf", help="Convert to PDF.")
+@option("-d", "--docx", "target", flag_value="docx", help="Convert to DOCX.")
+@option("-r", "--rtf", "target", flag_value="rtf", help="Convert to RTF.")
+@option("-t", "--txt", "target", flag_value="txt", help="Convert to TXT.")
+@option("-h", "--html", "target", flag_value="html", help="Convert to HTML.")
+@option("-k", "--keep-open", is_flag=True, help="Keep Microsoft Word open.")
+@version_option(__version__, "-V", "--version")
+def cli(inputs, output, target, keep_open):
+    """Main CLI entry point."""
+    if not inputs:
+        raise UsageError("No input files specified.")
+
+    if output is not None and target is not None:
+        raise UsageError("Cannot use both --output and format flags together.")
+
+    # --- MULTIPLE INPUTS ---
+    if len(inputs) > 1:
+        if output is None:
+            raise UsageError("Multiple inputs require --output DIRECTORY.")
+
+        if output.exists() and not output.is_dir():
+            raise UsageError("--output must be a directory for multiple inputs.")
+
+        output.mkdir(parents=True, exist_ok=True)
+
+        if target is None:
+            target = "pdf"
+
+        for inp in inputs:
+            out_file = output / (inp.stem + f".{target}")
+            try:
+                result = conver(inp, out_file, keep_open=keep_open)
+                echo(result)
+            except ConverError as err:
+                fail("Error:", err, err.error_code or 1)
+
+    # --- SINGLE INPUT ---
+    else:
+        inp = inputs[0]
+
+        if output is not None:
+            try:
+                result = conver(inp, output, keep_open=keep_open)
+                echo(result)
+            except ConverError as err:
+                fail("Error:", err, err.error_code or 1)
+        else:
+            if target is None:
+                target = "pdf"
+
+            out_file = inp.with_suffix("." + target)
+            try:
+                result = conver(inp, out_file, keep_open=keep_open)
+                echo(result)
+            except ConverError as err:
+                fail("Error:", err, err.error_code or 1)

conver/conver.py

@@ -0,0 +1,154 @@
+# Author: Timur Ulyahin, https://github.com/ucomru
+# License: MIT – provided "as-is" without any warranty or liability
+# Copyright: (c) 2024 Timur Ulyahin
+
+"""
+High-level document conversion API.
+
+This module exposes the `conver()` function — a Pythonic wrapper around the
+low-level IPC-based converter. It normalizes paths, performs minimal validation,
+invokes the underlying platform-specific script, and raises structured exceptions
+on failure.
+
+Successful conversion returns the resolved output path as a `Path` object.
+Errors are represented as subclasses of `ConverError`.
+"""
+
+from typing import Union, Tuple
+from pathlib import Path
+
+from ._convert import convert
+
+
+class ConverError(Exception):
+    def __init__(self, message, error_code=None):
+        super().__init__(message)
+        self.error_code = error_code
+
+
+class InputFileNotFound(ConverError):
+    pass
+
+
+class UnsupportedFormat(ConverError):
+    pass
+
+
+class WordStartError(ConverError):
+    pass
+
+
+class SaveError(ConverError):
+    pass
+
+
+class IPCError(ConverError):
+    pass
+
+
+class PlatformNotSupported(ConverError):
+    pass
+
+
+_ERROR_MAP = {
+    1: IPCError,
+    2: UnsupportedFormat,
+    3: UnsupportedFormat,
+    11: InputFileNotFound,
+    21: WordStartError,
+    31: SaveError,
+    98: IPCError,
+    99: PlatformNotSupported,
+}
+
+
+def _normalize_paths(
+    input_path: Union[str, Path],
+    output_path: Union[str, Path],
+) -> Tuple[Path, Path]:
+    """
+    Normalize and resolve input/output paths.
+
+    Rules:
+    - input_path is converted to absolute Path.
+    - output_path:
+        * if only a filename is provided, it is placed into the same directory
+          as input_path;
+        * otherwise, it is resolved relative to the filesystem.
+    - All returned paths are absolute.
+    """
+
+    # Normalize input
+    in_path = Path(input_path).expanduser().absolute()
+
+    # Normalize output raw
+    out_raw = Path(output_path).expanduser()
+
+    # filename-only -> drop into input directory
+    if out_raw.parent == Path("."):
+        out_path = in_path.parent / out_raw
+    else:
+        out_path = out_raw
+
+    out_path = out_path.absolute()
+
+    return in_path, out_path
+
+
+def conver(
+    input_path: Union[str, Path],
+    output_path: Union[str, Path],
+    keep_open: bool = False,
+) -> Path:
+    """
+    Convert a document to another format via the platform-level converter.
+
+    Parameters
+    ----------
+    input_path : str or pathlib.Path
+        Path to the source document.
+    output_path : str or pathlib.Path
+        Target output path with desired extension.
+    keep_open : bool, default=False
+        Whether to keep Microsoft Word open after conversion.
+
+    Returns
+    -------
+    Path
+        The resolved absolute output path.
+
+    Raises
+    ------
+    InputFileNotFound
+        The input file does not exist.
+    UnsupportedFormat
+        The source or target format is not supported by the underlying converter.
+    WordStartError
+        Microsoft Word could not be started by the script.
+    SaveError
+        The document could not be saved in the target format.
+    IPCError
+        Communication with the script failed or produced invalid JSON.
+    PlatformNotSupported
+        The current OS is not supported.
+    """
+
+    in_path, out_path = _normalize_paths(input_path, output_path)
+
+    if not in_path.exists():
+        raise InputFileNotFound(f"Input file does not exist: {in_path}", 11)
+
+    result = convert(
+        input_path=str(in_path),
+        output_path=str(out_path),
+        keep_open=keep_open,
+    )
+
+    code = result.get("error_code", None)
+    msg = result.get("message", "Unknown error")
+
+    if code and code != 0:
+        exc_class = _ERROR_MAP.get(code, ConverError)
+        raise exc_class(f"[{code}] {msg}", code)
+
+    return out_path

conver/scripts/convert.jxa

@@ -0,0 +1,229 @@
+#!/usr/bin/osascript -l JavaScript
+
+/*
+Author: Timur Ulyahin, https://github.com/ucomru
+License: MIT – provided "as-is" without any warranty or liability
+Copyright: (c) 2024 Timur Ulyahin
+
+USAGE:
+    osascript -l JavaScript convert.jxa \
+      '{"input": "<inputPath>", "output": "<outputPath>", "keepOpen": true | false}'
+
+RECOMMENDED PATHS:
+    Use "~/Downloads/" for both <inputPath> and <outputPath>.
+
+SETUP (macOS):
+    1. Go to System Settings > Privacy & Security > Files and Folders
+    2. Under Microsoft Word, enable access to "Downloads Folder".
+
+SUPPORTED FORMATS:
+    The script supports the following file extensions for input and output:
+    - Microsoft Word (.docx)    // Modern Word document format
+    - Word 97-2003 (.doc)       // Legacy Word document format
+    - PDF (.pdf)                // Export documents to PDF format
+    - Rich Text Format (.rtf)   // Basic document format with limited formatting
+    - OpenDocument Text (.odt)  // OpenOffice/LibreOffice document format
+    - Plain Text (.txt)         // Plain text format without any formatting
+    - HTML (.html)              // Web page format for viewing in browsers
+
+PARAMETERS:
+    - input: "<path to input file>"     // Path to the input file (required)
+    - output: "<path to output file>"   // Path to the output file (required)
+    - keepOpen: true | false            // Optional. Leave Word open after processing (default: false)
+
+STATUS SCHEMA (JSON Output):
+    The script outputs a JSON object with the following fields:
+    {
+        "status": "success" | "error",        // Execution status
+        "input": "<path to input file>",      // Path to the input file
+        "output": "<path to output file>",    // Path to the output file (null if error)
+        "message": "OK" | "<error message>",  // "OK" on success or specific error message
+        "error_code": 0 | <error code>        // 0 for success; specific code for different errors
+    }
+
+ERROR CODES:
+    0   - Success
+    1   - Incorrect JSON format or missing required fields
+    2   - Input file format is unsupported
+    3   - Output file format is unsupported
+    11  - Input file not found
+    21  - Microsoft Word did not start within the expected time
+    31  - Error saving or converting file
+*/
+
+ObjC.import("stdlib");
+const SystemEvents = Application("System Events");
+
+// Supported file formats with their corresponding codes in Word
+const formatCodes = {
+    "docx": 16,
+    "doc": 0,
+    "pdf": 17,
+    "rtf": 6,
+    "odt": 19,
+    "txt": 7,
+    "html": 8
+};
+
+// Retrieve the format code based on file extension, if supported
+function getFormatCodeByExtension(extension) {
+    const ext = extension.toLowerCase();
+    return ext in formatCodes ? formatCodes[ext] : null;
+}
+
+function run(argv) {
+    // Ensure there is only one JSON argument passed to the script
+    if (argv.length !== 1) {
+        console.log(JSON.stringify({
+            "status": "error",
+            "input": null,
+            "output": null,
+            "message": "A single JSON argument is required.",
+            "error_code": 1
+        }));
+        $.exit(1);
+    }
+
+    let params;
+    // Attempt to parse the JSON input
+    try {
+        params = JSON.parse(argv[0]);
+    } catch (error) {
+        console.log(JSON.stringify({
+            "status": "error",
+            "input": null,
+            "output": null,
+            "message": "Invalid JSON format.",
+            "error_code": 1
+        }));
+        $.exit(1);
+    }
+
+    const inputPath = params.input;
+    let outputPath = params.output;
+    const keepOpen = params.keepOpen === true;  // Flag to optionally keep Word open
+
+    // Validate the presence of required fields
+    if (!inputPath || !outputPath) {
+        console.log(JSON.stringify({
+            "status": "error",
+            "input": inputPath || null,
+            "output": outputPath || null,
+            "message": "Both 'input' and 'output' fields are required in JSON.",
+            "error_code": 1
+        }));
+        $.exit(1);
+    }
+
+    // Check if input file format is supported
+    const inputExtension = inputPath.split('.').pop().toLowerCase();
+    const inputFormat = getFormatCodeByExtension(inputExtension);
+
+    if (inputFormat === null) {
+        console.log(JSON.stringify({
+            "status": "error",
+            "input": inputPath,
+            "output": null,
+            "message": `The input file format "${inputExtension}" is unsupported.`,
+            "error_code": 2
+        }));
+        $.exit(2);
+    }
+
+    // Check if output file format is supported
+    const outputExtension = outputPath.split('.').pop().toLowerCase();
+    const outputFormat = getFormatCodeByExtension(outputExtension);
+
+    if (outputFormat === null) {
+        console.log(JSON.stringify({
+            "status": "error",
+            "input": inputPath,
+            "output": outputPath,
+            "message": `The output file format "${outputExtension}" is unsupported.`,
+            "error_code": 3
+        }));
+        $.exit(3);
+    }
+
+    const Word = Application("Microsoft Word");
+    Word.includeStandardAdditions = true;
+
+    let wordStartedByScript = false;  // Flag to track if Word was started by this script
+
+    try {
+        // Check if the input file exists
+        const fileManager = $.NSFileManager.defaultManager;
+        if (!fileManager.fileExistsAtPath($(inputPath))) {
+            console.log(JSON.stringify({
+                "status": "error",
+                "input": inputPath,
+                "output": null,
+                "message": `File "${inputPath}" not found.`,
+                "error_code": 11
+            }));
+            $.exit(11);
+        }
+
+        // Activate or launch Word if not already running
+        if (!Word.running()) {
+            Word.activate();
+            wordStartedByScript = true;  // Mark that Word was launched by this script
+
+            let attempt = 0;
+            // Wait for Word to start, with a maximum number of attempts
+            while (!Word.running() && attempt < 10) {
+                delay(0.1);
+                attempt++;
+            }
+
+            // Check if Word started successfully
+            if (Word.running()) {
+                SystemEvents.processes["Microsoft Word"].visible = false;
+            } else {
+                console.log(JSON.stringify({
+                    "status": "error",
+                    "input": inputPath,
+                    "output": outputPath,
+                    "message": "Microsoft Word did not start within the expected time.",
+                    "error_code": 21
+                }));
+                $.exit(21);
+            }
+        } else {
+            Word.launch();
+            SystemEvents.processes["Microsoft Word"].visible = false;
+        }
+
+        // Open the document and save it in the desired format
+        Word.open(inputPath);
+        const doc = Word.documents[0];
+        doc.saveAs({
+            fileName: outputPath,
+            fileFormat: outputFormat
+        });
+        doc.close({ saving: "no" });  // Close the document without saving any changes
+    } catch (error) {
+        console.log(JSON.stringify({
+            "status": "error",
+            "input": inputPath,
+            "output": outputPath,
+            "message": error.toString(),
+            "error_code": 31
+        }));
+        $.exit(31);
+    }
+
+    // Output success message in JSON format
+    console.log(JSON.stringify({
+        "status": "success",
+        "input": inputPath,
+        "output": outputPath,
+        "message": "OK",
+        "error_code": 0
+    }));
+
+    // Close Word if it was started by this script and keepOpen is false
+    if (wordStartedByScript && !keepOpen) {
+        Word.quit();
+    }
+}

conver/scripts/convert.ps1

@@ -0,0 +1,190 @@
+<#
+Author: Timur Ulyahin, https://github.com/ucomru
+License: MIT – provided "as-is" without any warranty or liability
+Copyright: (c) 2024 Timur Ulyahin
+
+USAGE:
+    powershell -ExecutionPolicy Bypass -File convert.ps1 -jsonArgs "{\"input\": \"<inputPath>\", \"output\": \"<outputPath>\", \"keepOpen\": true | false}"
+
+RECOMMENDED PATHS:
+    Use paths like "C:\Users\UserName\Downloads\" for both <inputPath> and <outputPath>.
+
+SETUP (Windows):
+    1. Ensure Microsoft Word is installed on your system.
+    2. If prompted, allow PowerShell to automate Microsoft Word.
+
+SUPPORTED FORMATS:
+    The script supports the following file extensions for input and output:
+    - Microsoft Word (.docx)    # Modern Word document format
+    - Word 97-2003 (.doc)       # Legacy Word document format
+    - PDF (.pdf)                # Export documents to PDF format
+    - Rich Text Format (.rtf)   # Basic document format with limited formatting
+    - OpenDocument Text (.odt)  # OpenOffice/LibreOffice document format
+    - Plain Text (.txt)         # Plain text format without any formatting
+    - HTML (.html)              # Web page format for viewing in browsers
+
+PARAMETERS:
+    - input: "<path to input file>"     # Path to the input file (required)
+    - output: "<path to output file>"   # Path to the output file (required)
+    - keepOpen: true | false            # Optional. Leave Word open after processing (default: false)
+
+STATUS SCHEMA (JSON Output):
+    The script outputs a JSON object with the following fields:
+    {
+        "status": "success" | "error",        # Execution status
+        "input": "<path to input file>",      # Path to the input file
+        "output": "<path to output file>",    # Path to the output file (null if error)
+        "message": "OK" | "<error message>",  # "OK" on success or specific error message
+        "error_code": 0 | <error code>        # 0 for success; specific code for different errors
+    }
+
+ERROR CODES:
+    0   - Success
+    1   - Incorrect JSON format or missing required fields
+    2   - Input file format is unsupported
+    3   - Output file format is unsupported
+    11  - Input file not found
+    21  - Microsoft Word did not start or is not installed
+    31  - Error saving or converting file
+#>
+
+param (
+    [string]$jsonArgs
+)
+
+# Supported file formats and corresponding codes for Microsoft Word
+$formatCodes = @{
+    "docx" = 16
+    "doc" = 0
+    "pdf" = 17
+    "rtf" = 6
+    "odt" = 19
+    "txt" = 7
+    "html" = 8
+}
+
+# Function to retrieve format code by extension
+function Get-FormatCodeByExtension {
+    param ($extension)
+    $extension = $extension.ToLower()
+    return $formatCodes[$extension] -as [int]
+}
+
+# Parse JSON input
+try {
+    $params = $jsonArgs | ConvertFrom-Json
+} catch {
+    Write-Output (ConvertTo-Json @{
+        status = "error"
+        input = $null
+        output = $null
+        message = "Invalid JSON format."
+        error_code = 1
+    })
+    exit 1
+}
+
+$inputPath = $params.input
+$outputPath = $params.output
+$keepOpen = $params.keepOpen -eq $true
+
+# Validate required parameters
+if (-not $inputPath -or -not $outputPath) {
+    Write-Output (ConvertTo-Json @{
+        status = "error"
+        input = $inputPath
+        output = $outputPath
+        message = "Both 'input' and 'output' fields are required in JSON."
+        error_code = 1
+    })
+    exit 1
+}
+
+# Check input file format support
+$inputExtension = [System.IO.Path]::GetExtension($inputPath).TrimStart('.').ToLower()
+$inputFormat = Get-FormatCodeByExtension -extension $inputExtension
+
+if (-not $inputFormat) {
+    Write-Output (ConvertTo-Json @{
+        status = "error"
+        input = $inputPath
+        output = $null
+        message = "The input file format '$inputExtension' is unsupported."
+        error_code = 2
+    })
+    exit 2
+}
+
+# Check output file format support
+$outputExtension = [System.IO.Path]::GetExtension($outputPath).TrimStart('.').ToLower()
+$outputFormat = Get-FormatCodeByExtension -extension $outputExtension
+
+if ($outputFormat -eq $null) {
+    Write-Output (ConvertTo-Json @{
+        status = "error"
+        input = $inputPath
+        output = $outputPath
+        message = "The output file format '$outputExtension' is unsupported."
+        error_code = 3
+    })
+    exit 3
+}
+
+# Initialize Word COM object with error handling
+try {
+    $word = New-Object -ComObject Word.Application -ErrorAction Stop
+} catch {
+    Write-Output (ConvertTo-Json @{
+        status = "error"
+        input = $inputPath
+        output = $outputPath
+        message = "Microsoft Word is not installed or cannot be started."
+        error_code = 21
+    })
+    exit 21
+}
+
+$word.Visible = $false
+$wordStartedByScript = $false
+
+try {
+    # Check if input file exists
+    if (-not (Test-Path -Path $inputPath)) {
+        Write-Output (ConvertTo-Json @{
+            status = "error"
+            input = $inputPath
+            output = $null
+            message = "File '$inputPath' not found."
+            error_code = 11
+        })
+        exit 11
+    }
+
+    # Open and convert the document
+    $doc = $word.Documents.Open($inputPath)
+    $doc.SaveAs([ref]$outputPath, [ref]$outputFormat)
+    $doc.Close()
+} catch {
+    Write-Output (ConvertTo-Json @{
+        status = "error"
+        input = $inputPath
+        output = $outputPath
+        message = $_.Exception.Message
+        error_code = 31
+    })
+    exit 31
+}
+
+# Success message
+Write-Output (ConvertTo-Json @{
+    status = "success"
+    input = $inputPath
+    output = $outputPath
+    message = "OK"
+    error_code = 0
+})
+
+# Close Word if opened by the script and keepOpen is false
+if (-not $keepOpen) {
+    $word.Quit()
+}

conver-0.1.0.dist-info/METADATA

@@ -0,0 +1,353 @@
+Metadata-Version: 2.4
+Name: conver
+Version: 0.1.0
+Summary: A cross-platform document converter.
+Author-email: Timur Ulyahin <ucomru@pm.me>
+License: MIT
+Project-URL: Homepage, https://github.com/ucomru/python-conver
+Project-URL: Repository, https://github.com/ucomru/python-conver
+Project-URL: Documentation, https://github.com/ucomru/python-conver
+Project-URL: Issues, https://github.com/ucomru/python-conver/issues
+Keywords: conversion,documents,office,tools,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click
+Dynamic: license-file
+
+# conver — Cross-platform Word Document Converter
+
+`conver` is a cross-platform Python package that converts Microsoft Word documents  
+using native system automation:
+
+- macOS: JXA (JavaScript for Automation)
+- Windows: PowerShell + Word COM automation
+
+The package provides:
+
+1. A high-level Python API: `conver.conver()`
+2. A command-line interface: `conver`
+3. A low-level IPC layer calling platform scripts  
+   (`convert.jxa` for macOS, `convert.ps1` for Windows)
+
+Conversion is performed via Microsoft Word itself, ensuring maximum compatibility 
+with `.docx`, `.doc`, `.rtf`, `.txt`, `.html`, `.odt`.
+
+---
+
+## Features
+
+- Cross-platform: macOS and Windows
+- Uses the actual Microsoft Word engine
+- Clean, minimal Python API
+- CLI with direct input/output or format-selection flags
+- Structured error handling via custom exceptions
+- Filename-only outputs automatically placed next to the input file
+- Safe low-level IPC layer between Python and native automation scripts
+
+## Installation
+
+### Using pip
+
+```bash
+pip install conver
+```
+
+### Recommended for CLI use: pipx
+
+If you primarily use `conver` as a command-line tool, it is best installed with **pipx**.  
+This isolates the package in its own virtual environment and avoids polluting your system Python:
+
+```bash
+pipx install conver
+```
+
+After installation:
+
+```bash
+conver --help
+```
+
+will be available globally.
+
+---
+
+### Requirements
+
+- Python **3.9+**  
+- Microsoft Word must be installed on the system  
+- macOS (JXA) or Windows (PowerShell + Word COM automation)  
+
+---
+
+## Python Usage
+
+### Basic example
+
+```python
+from conver import conver
+
+conver("document.docx", "document.pdf")
+```
+
+Returns:
+
+```python
+Path("/absolute/path/document.pdf")
+```
+
+### Filename-only output
+
+```python
+conver("/Users/me/docs/a.docx", "a.pdf")
+```
+
+Automatically produces:
+
+```bash
+/Users/me/docs/a.pdf
+```
+
+### Error handling example
+
+```python
+from conver import conver, UnsupportedFormat
+
+try:
+    conver("a.doc", "a.xyz")
+except UnsupportedFormat:
+    print("This output format is not supported.")
+```
+
+---
+
+## Python API Reference
+
+### `conver(input_path, output_path, keep_open=False) -> pathlib.Path`
+
+High-level document conversion function.
+
+#### Parameters
+
+- `input_path` — `str` or `pathlib.Path`  
+  Path to the source document.
+- `output_path` — `str` or `pathlib.Path`  
+  Target output filename or full path.
+- `keep_open` — `bool`  
+  Whether to keep Microsoft Word open after conversion.
+
+#### Returns
+- `pathlib.Path` — absolute path of the output file.
+
+#### Raises
+
+- `InputFileNotFound`
+- `UnsupportedFormat`
+- `WordStartError`
+- `SaveError`
+- `IPCError`
+- `PlatformNotSupported`
+
+---
+
+## CLI Usage
+
+The CLI supports two modes: direct output path, or format flags.
+
+### 1. Explicit input/output
+
+```bash
+conver input.docx output.pdf
+```
+
+### 2. Format flags (output placed next to input)
+
+```bash
+conver input.docx --pdf
+conver input.docx --rtf
+conver input.docx --txt
+conver input.docx --html
+conver input.docx --docx
+```
+
+If only one input file and no explicit output is given,
+the selected format determines the extension:
+
+```
+input.docx --pdf   -> input.pdf
+input.docx --rtf   -> input.rtf
+```
+
+### Output Behavior
+
+When OUTPUT is omitted, the resulting file is written next to the INPUT file.
+Examples:
+
+```
+    conver a.docx --pdf   -> a.pdf
+    conver /path/x.docx   -> /path/x.pdf
+```
+
+When multiple inputs are provided, --output must be a directory.  
+If the directory does not exist, it will be created automatically.
+
+### Default Format
+
+If no format flag is provided and no explicit output path is given,
+the default output format is **PDF**:
+
+```bash
+conver input.docx  # -> input.pdf
+```
+
+### CLI Syntax
+
+```
+Usage:
+    conver <input> <output>
+    conver <input> [--pdf | --docx | --rtf | --txt | --html] [--keep-open]
+
+Examples:
+    conver a.docx a.pdf
+    conver a.docx --pdf
+    conver /path/to/file.doc --html
+```
+
+### CLI Arguments
+
+`input`  
+    One or more input files. Patterns like `*.docx` are expanded by the shell.
+
+`output`  
+    Optional.  
+    For single input: output filename.  
+    For multiple inputs: must be a directory.
+
+---
+
+### Multiple Inputs (Batch Mode)
+
+The CLI can process multiple input files at once:
+
+```bash
+conver *.docx -o outdir
+conver file1.docx file2.docx file3.docx -o converted/
+```
+
+Rules:
+
+- When multiple inputs are provided, `--output` **must** point to a directory.
+- If the directory does not exist, it will be created automatically.
+- If no format flag is provided, the default output format is **PDF**.
+- Format flags (`--pdf`, `--rtf`, etc.) **cannot be used together with** `--output FILE`.
+- Globbing (`*.docx`) is expanded by your shell before reaching the CLI.
+
+Output filenames follow the pattern:
+
+```
+input.docx  ->  outdir/input.pdf
+```
+
+### Shell Globbing
+
+Patterns like `*.docx` are expanded by your shell before the `conver` command is executed.
+
+Examples:
+    `conver *.docx -o outdir`
+    `conver path/*.rtf --pdf`
+
+This means the CLI receives the expanded list of files as separate arguments.
+
+### Format-Flag Restrictions
+
+Format-selection flags:
+
+```
+--pdf  --docx  --rtf  --txt  --html
+```
+
+work **only when OUTPUT is omitted**, i.e.:
+
+*Allowed*:  
+```bash
+conver input.docx --pdf
+conver input.docx output.pdf
+```
+
+*Invalid:  
+```bash
+conver input.docx output.pdf --pdf
+```
+
+---
+
+## Supported Formats
+
+Conversion capabilities depend on Microsoft Word.
+
+Input formats: `.docx`, `.doc`, `.pdf`, `.rtf`, `.odt`, `.txt`, `.html`
+
+Output formats: `.pdf`, `.docx`, `.doc`, `.pdf`, `.rtf`, `.odt`, `.txt`, `.html`
+
+---
+
+## Platform Notes
+
+### macOS (JXA)
+
+The script `convert.jxa` runs through:
+
+```
+osascript -l JavaScript
+```
+
+macOS may require granting Microsoft Word file-access permissions.
+
+### Windows (PowerShell)
+
+The script `convert.ps1` uses:
+
+```
+Word.Application COM automation
+```
+
+If Word prompts the user, automation must be allowed.
+
+---
+
+## Low-Level Error Codes (Reference)
+
+These codes come from platform scripts and are mapped to exceptions by `conver()`:
+
+| Code | Meaning                              |
+|------|--------------------------------------|
+| 0    | Success                              |
+| 1    | Invalid JSON from stdin              |
+| 2    | Unsupported input format             |
+| 3    | Unsupported output format            |
+| 11   | Input file not found                 |
+| 21   | Word startup timeout                 |
+| 31   | Word could not save the file         |
+| 98   | Script produced invalid JSON         |
+| 99   | Unsupported platform                 |
+
+---
+
+## License
+
+MIT License  
+(c) 2024 Timur Ulyahin  
+https://github.com/ucomru
+
+---
+
+## Project Homepage
+
+GitHub:  
+https://github.com/ucomru/python-conver
+
+PyPI:  
+https://pypi.org/project/conver/

conver-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+conver/__init__.py,sha256=40DZmYJLiEt1HR6tZDm_ZjfhMvpHz57PAX5n8frB-9E,562
+conver/__version__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+conver/_convert.py,sha256=77EqKxxHBmNloK2HzR6zSKI28vxMWACzOJbrUHP1Vpg,7832
+conver/cli.py,sha256=RJ33rmI2uqdYgLH9dKqsJGWc-sO-DKoQ4sGhLdYRAW8,2790
+conver/conver.py,sha256=Ho6RiHVihQsk5AAJafte6fwCCS_5Sf5pyunouNHeMMQ,3780
+conver/scripts/convert.jxa,sha256=7aePzEWbFlPRihPxdgEFfiteyxVxkVhCji4EVq7djNk,7715
+conver/scripts/convert.ps1,sha256=qdm6lfoAUzD3HbyAMprWakQlbGMZW0Ow6KoLbmquOtE,5637
+conver-0.1.0.dist-info/licenses/LICENSE,sha256=EZ2rjk_EQKv3xS71Wwf41DAGJ4gdkeGhM5CGvn6Mf0A,1095
+conver-0.1.0.dist-info/METADATA,sha256=faEL7zeSRKrNj0dMkhYg-r7gxwomeh5_POMPDEFTeIs,7500
+conver-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+conver-0.1.0.dist-info/entry_points.txt,sha256=xILIEXchvJsg2IJFeYlxRDBRxLLPUT--y0Lo1kB_QCo,42
+conver-0.1.0.dist-info/top_level.txt,sha256=_pwrVeQgyeqp-yzROQqRFqK0S0tElmrsb8UXoDJCwiE,7
+conver-0.1.0.dist-info/RECORD,,

conver-0.1.0.dist-info/WHEEL

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

conver-0.1.0.dist-info/entry_points.txt

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

conver-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+© 2024 Timur Ulyahin, https://github.com/ucomru
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

conver-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+conver