convert-docs 0.3.0__tar.gz → 0.4.0__tar.gz

{convert_docs-0.3.0 → convert_docs-0.4.0}/PKG-INFO

@@ -1,36 +1,34 @@
 Metadata-Version: 2.4
 Name: convert-docs
-Version: 0.3.0
-Summary: Recursively convert documents (pdf, docx, pptx, xlsx, ...) to Markdown via markitdown, mirroring the source folder structure into a destination folder.
+Version: 0.4.0
+Summary: Convert documents (pdf, docx, pptx, xlsx, ...) to Markdown via markitdown, recursively for a folder or directly for a single file.
 Requires-Python: >=3.10
 Requires-Dist: markitdown[docx,outlook,pdf,pptx,xls,xlsx]>=0.1.5
 Description-Content-Type: text/markdown
 
 # convert-docs
 
-Recursively convert documents (pdf, docx, pptx, xlsx, and more) to Markdown via
-[markitdown](https://github.com/microsoft/markitdown), mirroring the source folder
-structure into a destination folder.
+Convert documents (pdf, docx, pptx, xlsx, and more) to Markdown via
+[markitdown](https://github.com/microsoft/markitdown). Point it at a folder and it
+recursively converts everything, mirroring the structure into a destination folder;
+point it at a single file and it converts just that file.
 
 ## Install
 
-Requires [uv](https://docs.astral.sh/uv/). If you don't have it yet:
+Requires Python 3.10+.
 
 ```bash
-# macOS / Linux
-curl -LsSf https://astral.sh/uv/install.sh | sh
-
-# Windows (PowerShell)
-powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+uv tool install convert-docs
 ```
 
-Then install the tool:
+Don't have [uv](https://docs.astral.sh/uv/)? Install it first:
 
 ```bash
-uv tool install convert-docs
+curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows
 ```
 
-No `uv`? Plain `pip` also works, as long as it's Python 3.10+: `pip install convert-docs`.
+Or skip uv entirely and use pip: `pip install convert-docs`
 
 ## Usage
 
@@ -40,6 +38,13 @@ Run with no flags for an interactive prompt (asks for source, then destination):
 convert-docs
 ```
 
+Tip (macOS): select a file or folder in Finder and press `Option+Command+C` to copy
+its full path, then paste it into the prompt.
+
+Pointing it at a single file converts just that file, writing the `.md` next to it by
+default. To use a different output name, append a comma and the new name at the source
+prompt: `~/Downloads/Report.pdf, quarterly-summary` writes `quarterly-summary.md`.
+
 Or pass flags to skip the prompts:
 
 ```bash
@@ -48,33 +53,29 @@ convert-docs -e pdf,docx        # restrict which extensions get converted
 convert-docs -f                 # force re-conversion, ignoring the up-to-date skip
 convert-docs --last             # re-run with the same source/destination/extensions as last time
 convert-docs -j 8                # convert 8 files in parallel instead of the default 4
+convert-docs -n                  # dry run: show what would happen, write nothing
 ```
 
 | Flag | Description |
 |---|---|
-| `-s, --source` | Source directory to scan (skips the interactive prompt) |
-| `-o, --output` | Output directory, mirrors source structure (skips the interactive prompt) |
+| `-s, --source` | Source file or directory to convert (skips the interactive prompt) |
+| `-o, --output` | Output directory (mirrors source structure), or for a single-file source, an output directory or file path (skips the interactive prompt) |
 | `-e, --ext` | Comma-separated extensions to convert |
 | `-f, --force` | Force re-conversion even if output `.md` already exists and is up to date |
 | `-l, --last` | Reuse the source, destination, and extensions from the last run (skips prompts; cannot be combined with `-s`/`-o`) |
 | `-j, --jobs` | Convert this many files in parallel using separate processes (default: `min(4, cpu_count)`; use `1` for sequential) |
+| `-n, --dry-run` | Show what would be converted, skipped, or collide, without writing anything |
+| `--log-file` | Append this run's output to a file as well as stdout |
+| `--version` | Print the installed version and exit |
 
 Files with unsupported extensions are listed at the end instead of being silently
 skipped, and any conversion failures are reported with the underlying error.
+Common noise directories (`.git`, `node_modules`, `.venv`, `__pycache__`, etc.) are
+skipped automatically. If two source files would produce the same output path (e.g.
+`report.docx` and `report.pdf` both map to `report.md`), the first is converted and
+the rest are reported as collisions rather than silently overwritten.
 
-### Parallel conversion
-
-Files convert using separate OS processes (real parallelism across CPU cores, not
-`asyncio` — conversion is CPU-bound parsing work, not I/O waiting, so asyncio's
-cooperative concurrency wouldn't actually help). Benchmarked on a 10-core Mac converting
-12–30 real docx files: `-j 4` (the default) cut wall time by ~2.3x vs. sequential.
-Pushing higher didn't help further — `-j 8` was consistently *slower* than `-j 4` in
-testing, since each worker process pays a fixed startup cost importing `markitdown`'s
-dependencies (onnxruntime, magika, pandas), which outweighs the extra parallelism for
-typical batch sizes. If you're converting a very large batch (hundreds of files), it's
-worth experimenting with higher `-j` values yourself; for typical folders the default
-is a reasonable balance. Progress lines print in completion order, not scan order, since
-files finish out of sequence when running in parallel.
+Paths are highlighted in supported terminals; set `NO_COLOR=1` to disable.
 
 ### Re-running on new files
 
@@ -90,3 +91,9 @@ since scheduled jobs don't load your shell profile).
 ```bash
 uv tool upgrade convert-docs
 ```
+
+## Development
+
+```bash
+uv run pytest
+```

{convert_docs-0.3.0 → convert_docs-0.4.0}/README.md

@@ -1,28 +1,26 @@
 # convert-docs
 
-Recursively convert documents (pdf, docx, pptx, xlsx, and more) to Markdown via
-[markitdown](https://github.com/microsoft/markitdown), mirroring the source folder
-structure into a destination folder.
+Convert documents (pdf, docx, pptx, xlsx, and more) to Markdown via
+[markitdown](https://github.com/microsoft/markitdown). Point it at a folder and it
+recursively converts everything, mirroring the structure into a destination folder;
+point it at a single file and it converts just that file.
 
 ## Install
 
-Requires [uv](https://docs.astral.sh/uv/). If you don't have it yet:
+Requires Python 3.10+.
 
 ```bash
-# macOS / Linux
-curl -LsSf https://astral.sh/uv/install.sh | sh
-
-# Windows (PowerShell)
-powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+uv tool install convert-docs
 ```
 
-Then install the tool:
+Don't have [uv](https://docs.astral.sh/uv/)? Install it first:
 
 ```bash
-uv tool install convert-docs
+curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows
 ```
 
-No `uv`? Plain `pip` also works, as long as it's Python 3.10+: `pip install convert-docs`.
+Or skip uv entirely and use pip: `pip install convert-docs`
 
 ## Usage
 
@@ -32,6 +30,13 @@ Run with no flags for an interactive prompt (asks for source, then destination):
 convert-docs
 ```
 
+Tip (macOS): select a file or folder in Finder and press `Option+Command+C` to copy
+its full path, then paste it into the prompt.
+
+Pointing it at a single file converts just that file, writing the `.md` next to it by
+default. To use a different output name, append a comma and the new name at the source
+prompt: `~/Downloads/Report.pdf, quarterly-summary` writes `quarterly-summary.md`.
+
 Or pass flags to skip the prompts:
 
 ```bash
@@ -40,33 +45,29 @@ convert-docs -e pdf,docx        # restrict which extensions get converted
 convert-docs -f                 # force re-conversion, ignoring the up-to-date skip
 convert-docs --last             # re-run with the same source/destination/extensions as last time
 convert-docs -j 8                # convert 8 files in parallel instead of the default 4
+convert-docs -n                  # dry run: show what would happen, write nothing
 ```
 
 | Flag | Description |
 |---|---|
-| `-s, --source` | Source directory to scan (skips the interactive prompt) |
-| `-o, --output` | Output directory, mirrors source structure (skips the interactive prompt) |
+| `-s, --source` | Source file or directory to convert (skips the interactive prompt) |
+| `-o, --output` | Output directory (mirrors source structure), or for a single-file source, an output directory or file path (skips the interactive prompt) |
 | `-e, --ext` | Comma-separated extensions to convert |
 | `-f, --force` | Force re-conversion even if output `.md` already exists and is up to date |
 | `-l, --last` | Reuse the source, destination, and extensions from the last run (skips prompts; cannot be combined with `-s`/`-o`) |
 | `-j, --jobs` | Convert this many files in parallel using separate processes (default: `min(4, cpu_count)`; use `1` for sequential) |
+| `-n, --dry-run` | Show what would be converted, skipped, or collide, without writing anything |
+| `--log-file` | Append this run's output to a file as well as stdout |
+| `--version` | Print the installed version and exit |
 
 Files with unsupported extensions are listed at the end instead of being silently
 skipped, and any conversion failures are reported with the underlying error.
+Common noise directories (`.git`, `node_modules`, `.venv`, `__pycache__`, etc.) are
+skipped automatically. If two source files would produce the same output path (e.g.
+`report.docx` and `report.pdf` both map to `report.md`), the first is converted and
+the rest are reported as collisions rather than silently overwritten.
 
-### Parallel conversion
-
-Files convert using separate OS processes (real parallelism across CPU cores, not
-`asyncio` — conversion is CPU-bound parsing work, not I/O waiting, so asyncio's
-cooperative concurrency wouldn't actually help). Benchmarked on a 10-core Mac converting
-12–30 real docx files: `-j 4` (the default) cut wall time by ~2.3x vs. sequential.
-Pushing higher didn't help further — `-j 8` was consistently *slower* than `-j 4` in
-testing, since each worker process pays a fixed startup cost importing `markitdown`'s
-dependencies (onnxruntime, magika, pandas), which outweighs the extra parallelism for
-typical batch sizes. If you're converting a very large batch (hundreds of files), it's
-worth experimenting with higher `-j` values yourself; for typical folders the default
-is a reasonable balance. Progress lines print in completion order, not scan order, since
-files finish out of sequence when running in parallel.
+Paths are highlighted in supported terminals; set `NO_COLOR=1` to disable.
 
 ### Re-running on new files
 
@@ -82,3 +83,9 @@ since scheduled jobs don't load your shell profile).
 ```bash
 uv tool upgrade convert-docs
 ```
+
+## Development
+
+```bash
+uv run pytest
+```

{convert_docs-0.3.0 → convert_docs-0.4.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "convert-docs"
-version = "0.3.0"
-description = "Recursively convert documents (pdf, docx, pptx, xlsx, ...) to Markdown via markitdown, mirroring the source folder structure into a destination folder."
+version = "0.4.0"
+description = "Convert documents (pdf, docx, pptx, xlsx, ...) to Markdown via markitdown, recursively for a folder or directly for a single file."
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
@@ -11,6 +11,9 @@ dependencies = [
 [project.scripts]
 convert-docs = "convert_docs.cli:main"
 
+[dependency-groups]
+dev = ["pytest>=8"]
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"