conver 0.1.0__tar.gz

conver-0.1.0/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/MANIFEST.in

@@ -0,0 +1,6 @@
+# Include essential documentation files
+include README.md
+include LICENSE
+
+# Recursively include all files in the scripts folder within src/conver
+recursive-include src/conver/scripts *

conver-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,333 @@
+# 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/