Skip to content

A fast, helpful, and open-source document parser

fix: correct Python wrapper docs, code, and CLI discovery

AdemBoukhris457a1f116a9df4a
diff --git a/docs/src/content/docs/liteparse/guides/library-usage.md b/docs/src/content/docs/liteparse/guides/library-usage.md
index 2ea944f..6f3b1e7 100644
--- a/docs/src/content/docs/liteparse/guides/library-usage.md
+++ b/docs/src/content/docs/liteparse/guides/library-usage.md
@@ -115,16 +115,24 @@ See the [API reference](/liteparse/api/) for full type details.
## Python
-The Python package wraps the LiteParse CLI, so the Node.js CLI must be installed first.
+The Python package is a wrapper around the LiteParse Node.js CLI. **Node.js (>= 18) must be installed** on your system.
### Installation
+First, install the LiteParse CLI:
+
+```bash
+npm install -g @llamaindex/liteparse
+```
+
+Then install the Python package:
+
```bash
pip install liteparse
```
<Aside type="caution">
- The Python package calls the LiteParse CLI under the hood: while the package can auto-install the CLI executable if not installed, it is recommended to do it separately (`npm install -g @llamaindex/liteparse` or `brew install run-llama/liteparse/llamaindex-liteparse`).
+ The Python package calls the LiteParse CLI under the hood via subprocess. Node.js (>= 18) is required. While the package can auto-install the CLI via `npm install -g @llamaindex/liteparse` on first use, it is recommended to install it separately beforehand.
</Aside>
### Parsing a document
@@ -145,28 +153,31 @@ for page in result.pages:
### Configuration
-Options can be set on the constructor (applied to all parse calls) or per-call:
+The `LiteParse` constructor accepts `cli_path` (to override CLI auto-detection) and `install_if_not_available` (to control auto-install behavior). All parsing options are passed per-call:
```python
-# Constructor-level defaults
-parser = LiteParse(
+parser = LiteParse()
+
+result = parser.parse(
+ "document.pdf",
ocr_enabled=True,
ocr_server_url="http://localhost:8828/ocr",
ocr_language="fra",
dpi=300,
+ target_pages="1-5",
password="secret", # for encrypted/protected documents
)
-
-# Per-call options
-result = parser.parse("document.pdf", target_pages="1-5")
```
### Parsing from bytes
-If you already have file contents in memory (e.g. from a web upload):
+If you already have file contents in memory (e.g. from a web upload), pass them directly to `parse()`:
```python
-result = parser.parse_bytes(pdf_bytes, filename="upload.pdf")
+with open("document.pdf", "rb") as f:
+ pdf_bytes = f.read()
+
+result = parser.parse(pdf_bytes)
print(result.text)
```
@@ -182,5 +193,5 @@ result = parser.batch_parse(
extension_filter=".pdf",
)
-print(f"Parsed {result.success_count} files in {result.total_time_seconds}s")
+print(f"Output written to: {result.output_dir}")
```
diff --git a/packages/python/README.md b/packages/python/README.md
index 0aaf848..5871876 100644
--- a/packages/python/README.md
+++ b/packages/python/README.md
@@ -2,20 +2,31 @@
Python wrapper for [LiteParse](https://github.com/run-llama/liteparse) - fast, lightweight document parsing with optional OCR.
+> **Important:** This package is a Python wrapper around the LiteParse Node.js CLI.
+> You must have **Node.js** (>= 18) installed on your system. The CLI will be auto-installed
+> via npm on first use if not already present, or you can install it manually beforehand.
+
## Installation
+### Step 1: Install Node.js
+
+LiteParse requires Node.js (>= 18). Install it from [nodejs.org](https://nodejs.org/) or via your package manager.
+
+### Step 2: Install the LiteParse CLI
+
```bash
-pip install liteparse
+npm install -g @llamaindex/liteparse
```
-While the python package can auto-install the LiteParse CLI if not installed, it is recommended to do it separately:
+### Step 3: Install the Python package
```bash
-npm install -g liteparse
-# or
-npx liteparse --version
+pip install liteparse
```
+> **Note:** If you skip Step 2, the Python package will attempt to auto-install the CLI
+> via `npm install -g @llamaindex/liteparse` on first use (requires npm in your PATH).
+
## Quick Start
```python
@@ -35,6 +46,8 @@ for page in result.pages:
## Configuration
+All parsing options are passed per-call to `parse()`:
+
```python
from liteparse import LiteParse
@@ -45,11 +58,23 @@ result = parser.parse(
ocr_enabled=False,
max_pages=10,
dpi=150,
- preserve_small_text=True,
+ preserve_very_small_text=True,
)
print(result.text)
```
+## Parsing from bytes
+
+If you already have file contents in memory (e.g. from a web upload), pass them directly:
+
+```python
+with open("document.pdf", "rb") as f:
+ pdf_bytes = f.read()
+
+result = parser.parse(pdf_bytes)
+print(result.text)
+```
+
## Batch Processing
For parsing multiple files, batch mode is significantly faster as it reuses the PDF engine:
@@ -57,18 +82,18 @@ For parsing multiple files, batch mode is significantly faster as it reuses the
```python
from liteparse import LiteParse
-parser = LiteParse(ocr_enabled=False)
+parser = LiteParse()
# Parse all documents in a directory
result = parser.batch_parse(
input_dir="./documents",
output_dir="./output",
+ ocr_enabled=False,
recursive=True, # Include subdirectories
extension_filter=".pdf", # Only PDF files
)
-print(f"Parsed {result.success_count} files in {result.total_time_seconds}s")
-print(f"Average: {result.avg_time_ms}ms per file")
+print(f"Output written to: {result.output_dir}")
```
## Supported Formats
@@ -83,7 +108,7 @@ print(f"Average: {result.avg_time_ms}ms per file")
1. **Disable OCR** if your documents have selectable text:
```python
- parser = LiteParse(ocr_enabled=False)
+ result = parser.parse("doc.pdf", ocr_enabled=False)
```
2. **Use batch mode** for multiple files to avoid cold-start overhead:
diff --git a/packages/python/liteparse/__init__.py b/packages/python/liteparse/__init__.py
index 4dd104d..d95fb17 100644
--- a/packages/python/liteparse/__init__.py
+++ b/packages/python/liteparse/__init__.py
@@ -16,7 +16,7 @@ from .types import (
CLINotFoundError,
)
-__version__ = "1.0.0"
+__version__ = "1.2.0"
__all__ = [
# Main class
"LiteParse",
diff --git a/packages/python/liteparse/parser.py b/packages/python/liteparse/parser.py
index b3c96c5..2ca0b54 100644
--- a/packages/python/liteparse/parser.py
+++ b/packages/python/liteparse/parser.py
@@ -35,7 +35,7 @@ def _find_cli(install_if_not_available: bool) -> str:
# Check if npx is available
npx_path = shutil.which("npx")
if npx_path:
- return "npx liteparse"
+ return "npx @llamaindex/liteparse"
# Check common node_modules locations
possible_paths = [
@@ -49,9 +49,17 @@ def _find_cli(install_if_not_available: bool) -> str:
return os.path.abspath(path)
if install_if_not_available:
+ npm_path = shutil.which("npm")
+ if not npm_path:
+ raise CLINotFoundError(
+ "liteparse CLI not found and npm is not available to auto-install it.\n"
+ "Please install Node.js (>= 18) from https://nodejs.org/ and then run:\n"
+ " npm install -g @llamaindex/liteparse"
+ )
warnings.warn(
- "liteparse CLI could not be find. Running `npm install -g @llamaindex/liteparse` to install it.",
+ "liteparse CLI could not be found. Running `npm install -g @llamaindex/liteparse` to install it.",
UserWarning,
+ stacklevel=2,
)
result = subprocess.run(
["npm", "install", "-g", "@llamaindex/liteparse"],
@@ -67,7 +75,8 @@ def _find_cli(install_if_not_available: bool) -> str:
return cli_path
raise CLINotFoundError(
- "liteparse CLI not found. Please install it with: npm i -g @llamaindex/liteparse"
+ "liteparse CLI not found. Please install Node.js (>= 18) and then run:\n"
+ " npm install -g @llamaindex/liteparse"
)