Skip to content

A fast, helpful, and open-source document parser

add tests and some fixes to python wrapper

Logan Markewichd082f24f7964
diff --git a/packages/python/liteparse/parser.py b/packages/python/liteparse/parser.py
index 61f6811..cb43213 100644
--- a/packages/python/liteparse/parser.py
+++ b/packages/python/liteparse/parser.py
@@ -61,14 +61,11 @@ def _parse_json_result(json_data: dict) -> ParseResult:
for item in page_data.get("textItems", []):
text_items.append(
TextItem(
- str=item.get("str", ""),
+ text=item.get("text", ""),
x=item.get("x", 0),
y=item.get("y", 0),
width=item.get("width", 0),
height=item.get("height", 0),
- w=item.get("w", 0),
- h=item.get("h", 0),
- r=item.get("r", 0),
fontName=item.get("fontName"),
fontSize=item.get("fontSize"),
)
@@ -111,12 +108,13 @@ def _build_parse_cli_args(
ocr_enabled: bool,
ocr_server_url: Optional[str],
ocr_language: str,
+ num_workers: Optional[int],
max_pages: int,
target_pages: Optional[str],
dpi: int,
precise_bounding_box: bool,
- skip_diagonal_text: bool,
preserve_very_small_text: bool,
+ password: Optional[str],
) -> List[str]:
"""Build CLI arguments for parse command."""
args: List[str] = ["--format", "json"]
@@ -127,6 +125,10 @@ def _build_parse_cli_args(
args.extend(["--ocr-server-url", ocr_server_url])
args.extend(["--ocr-language", ocr_language])
+
+ if num_workers is not None:
+ args.extend(["--num-workers", str(num_workers)])
+
args.extend(["--max-pages", str(max_pages)])
if target_pages:
@@ -137,12 +139,12 @@ def _build_parse_cli_args(
if not precise_bounding_box:
args.append("--no-precise-bbox")
- if skip_diagonal_text:
- args.append("--skip-diagonal-text")
-
if preserve_very_small_text:
args.append("--preserve-small-text")
+ if password:
+ args.extend(["--password", password])
+
args.append("-q")
return args
@@ -152,11 +154,13 @@ def _build_batch_cli_args(
ocr_enabled: bool,
ocr_server_url: Optional[str],
ocr_language: str,
+ num_workers: Optional[int],
max_pages: int,
dpi: int,
precise_bounding_box: bool,
recursive: bool,
extension_filter: Optional[str],
+ password: Optional[str],
) -> List[str]:
"""Build CLI arguments for batch-parse command."""
args: List[str] = ["--format", output_format.value]
@@ -167,6 +171,10 @@ def _build_batch_cli_args(
args.extend(["--ocr-server-url", ocr_server_url])
args.extend(["--ocr-language", ocr_language])
+
+ if num_workers is not None:
+ args.extend(["--num-workers", str(num_workers)])
+
args.extend(["--max-pages", str(max_pages)])
args.extend(["--dpi", str(dpi)])
@@ -179,6 +187,10 @@ def _build_batch_cli_args(
if extension_filter:
args.extend(["--extension", extension_filter])
+ if password:
+ args.extend(["--password", password])
+
+ args.append("-q")
return args
@@ -219,12 +231,13 @@ class LiteParse:
ocr_enabled: bool = True,
ocr_server_url: Optional[str] = None,
ocr_language: str = "en",
- max_pages: int = 1000,
+ num_workers: Optional[int] = None,
+ max_pages: int = 10000,
target_pages: Optional[str] = None,
dpi: int = 150,
precise_bounding_box: bool = True,
- skip_diagonal_text: bool = False,
preserve_very_small_text: bool = False,
+ password: Optional[str] = None,
timeout: Optional[float] = None,
) -> ParseResult:
"""
@@ -235,14 +248,14 @@ class LiteParse:
ocr_enabled: Whether to enable OCR for scanned documents
ocr_server_url: URL of HTTP OCR server (uses Tesseract if not provided)
ocr_language: Language code for OCR (e.g., "en", "fr", "de")
+ num_workers: Number of pages to OCR in parallel (defaults to CPU cores - 1)
max_pages: Maximum number of pages to parse
target_pages: Specific pages to parse (e.g., "1-5,10,15-20")
dpi: DPI for rendering (affects OCR quality)
precise_bounding_box: Whether to compute precise bounding boxes
- skip_diagonal_text: Whether to skip diagonal text
preserve_very_small_text: Whether to preserve very small text
+ password: Password for encrypted/protected documents
timeout: Timeout in seconds (None for no timeout)
- quiet: Whether to suppress CLI output (overrides -q flag)
Returns:
ParseResult containing the parsed document data
@@ -264,12 +277,13 @@ class LiteParse:
ocr_enabled=ocr_enabled,
ocr_server_url=ocr_server_url,
ocr_language=ocr_language,
+ num_workers=num_workers,
max_pages=max_pages,
target_pages=target_pages,
dpi=dpi,
precise_bounding_box=precise_bounding_box,
- skip_diagonal_text=skip_diagonal_text,
preserve_very_small_text=preserve_very_small_text,
+ password=password,
)
)
@@ -306,11 +320,13 @@ class LiteParse:
ocr_enabled: bool = True,
ocr_server_url: Optional[str] = None,
ocr_language: str = "en",
- max_pages: int = 1000,
+ num_workers: Optional[int] = None,
+ max_pages: int = 10000,
dpi: int = 150,
precise_bounding_box: bool = True,
recursive: bool = False,
extension_filter: Optional[str] = None,
+ password: Optional[str] = None,
timeout: Optional[float] = None,
) -> BatchResult:
"""
@@ -326,11 +342,13 @@ class LiteParse:
ocr_enabled: Whether to enable OCR for scanned documents
ocr_server_url: URL of HTTP OCR server (uses Tesseract if not provided)
ocr_language: Language code for OCR
+ num_workers: Number of pages to OCR in parallel (defaults to CPU cores - 1)
max_pages: Maximum number of pages to parse per file
dpi: DPI for rendering
precise_bounding_box: Whether to compute precise bounding boxes
recursive: Whether to recursively search subdirectories
extension_filter: Only process files with this extension (e.g., ".pdf")
+ password: Password for encrypted/protected documents (applied to all files)
timeout: Timeout in seconds for the entire batch
Returns:
@@ -362,11 +380,13 @@ class LiteParse:
ocr_enabled=ocr_enabled,
ocr_server_url=ocr_server_url,
ocr_language=ocr_language,
+ num_workers=num_workers,
max_pages=max_pages,
dpi=dpi,
precise_bounding_box=precise_bounding_box,
recursive=recursive,
extension_filter=extension_filter,
+ password=password,
)
)
@@ -392,6 +412,7 @@ class LiteParse:
target_pages: Optional[str] = None,
dpi: int = 150,
image_format: Union[ImageFormat, str] = ImageFormat.PNG,
+ password: Optional[str] = None,
load_bytes: bool = False,
timeout: Optional[float] = None,
) -> ScreenshotBatchResult:
@@ -404,6 +425,7 @@ class LiteParse:
target_pages: Specific pages to screenshot (e.g., "1,3,5" or "1-5")
dpi: DPI for rendering
image_format: Image format ("png" or "jpg")
+ password: Password for encrypted/protected documents
load_bytes: If True, load image bytes into ScreenshotResult objects
timeout: Timeout in seconds
@@ -442,6 +464,9 @@ class LiteParse:
if target_pages:
cmd.extend(["--target-pages", target_pages])
+ if password:
+ cmd.extend(["--password", password])
+
try:
result = subprocess.run(
cmd,
diff --git a/packages/python/liteparse/types.py b/packages/python/liteparse/types.py
index d04308a..976e86b 100644
--- a/packages/python/liteparse/types.py
+++ b/packages/python/liteparse/types.py
@@ -29,14 +29,11 @@ class BoundingBox:
@dataclass
class TextItem:
"""Individual text item extracted from a document."""
- str: str
+ text: str
x: float
y: float
width: float
height: float
- w: float
- h: float
- r: float # rotation
fontName: Optional[str] = None
fontSize: Optional[float] = None
diff --git a/packages/python/pyproject.toml b/packages/python/pyproject.toml
index d6eca20..cbe3dd5 100644
--- a/packages/python/pyproject.toml
+++ b/packages/python/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "liteparse"
-version = "1.0.0"
+version = "1.0.1"
description = "Python wrapper for LiteParse - fast, lightweight PDF and document parsing"
readme = "README.md"
license = "MIT"
@@ -48,6 +48,3 @@ python_version = "3.10"
strict = true
warn_return_any = true
warn_unused_ignores = true
-
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
diff --git a/packages/python/tests/__init__.py b/packages/python/tests/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/packages/python/tests/conftest.py b/packages/python/tests/conftest.py
new file mode 100644
index 0000000..2959571
--- /dev/null
+++ b/packages/python/tests/conftest.py
@@ -0,0 +1,46 @@
+"""Shared fixtures for e2e tests."""
+
+import os
+from pathlib import Path
+
+import pytest
+
+from liteparse import LiteParse
+
+# Resolve test-docs relative to the repo root
+REPO_ROOT = Path(__file__).resolve().parents[3]
+TEST_DOCS = REPO_ROOT / "test-docs"
+EXPECTED_DATASET = REPO_ROOT / "expected-dataset" / "data"
+
+
+def parser() -> LiteParse:
+ """LiteParse instance (auto-detects CLI)."""
+ return LiteParse()
+
+
+def invoice_pdf() -> Path:
+ """Path to a small single-page invoice PDF."""
+ p = TEST_DOCS / "invoice.pdf"
+ if not p.exists():
+ pytest.skip(f"Test document not found: {p}")
+ return p
+
+
+def two_page_pdf() -> Path:
+ """Path to a 2-page PDF."""
+ p = EXPECTED_DATASET / "2pages.pdf"
+ if not p.exists():
+ pytest.skip(f"Test document not found: {p}")
+ return p
+
+
+def empty_pdf() -> Path:
+ """Path to an empty PDF."""
+ p = EXPECTED_DATASET / "empty.pdf"
+ if not p.exists():
+ pytest.skip(f"Test document not found: {p}")
+ return p
diff --git a/packages/python/tests/test_batch_e2e.py b/packages/python/tests/test_batch_e2e.py
new file mode 100644
index 0000000..64ced51
--- /dev/null
+++ b/packages/python/tests/test_batch_e2e.py
@@ -0,0 +1,64 @@
+"""E2E tests for LiteParse.batch_parse() — validates Python types match CLI output."""
+
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from liteparse import (
+ LiteParse,
+ BatchResult,
+ OutputFormat,
+)
+
+
+class TestBatchParseBasic:
+ """Basic batch parsing functionality."""
+
+ def test_batch_parse_returns_batch_result(self, parser: LiteParse, invoice_pdf: Path):
+ input_dir = invoice_pdf.parent
+ with tempfile.TemporaryDirectory() as tmpdir:
+ result = parser.batch_parse(
+ input_dir,
+ tmpdir,
+ ocr_enabled=False,
+ extension_filter=".pdf",
+ )
+ assert isinstance(result, BatchResult)
+ assert result.output_dir == tmpdir
+
+ def test_batch_parse_creates_output_files(self, parser: LiteParse, invoice_pdf: Path):
+ input_dir = invoice_pdf.parent
+ with tempfile.TemporaryDirectory() as tmpdir:
+ parser.batch_parse(
+ input_dir,
+ tmpdir,
+ output_format=OutputFormat.TEXT,
+ ocr_enabled=False,
+ extension_filter=".pdf",
+ )
+ output_files = list(Path(tmpdir).rglob("*"))
+ # Should have produced at least one output file
+ assert len(output_files) > 0
+
+ def test_batch_parse_json_format(self, parser: LiteParse, invoice_pdf: Path):
+ input_dir = invoice_pdf.parent
+ with tempfile.TemporaryDirectory() as tmpdir:
+ parser.batch_parse(
+ input_dir,
+ tmpdir,
+ output_format="json",
+ ocr_enabled=False,
+ extension_filter=".pdf",
+ )
+ json_files = list(Path(tmpdir).rglob("*.json"))
+ assert len(json_files) > 0
+
+
+class TestBatchParseErrors:
+ """Test error handling."""
+
+ def test_input_dir_not_found(self, parser: LiteParse):
+ with tempfile.TemporaryDirectory() as tmpdir:
+ with pytest.raises(FileNotFoundError):
+ parser.batch_parse("/nonexistent/dir", tmpdir)
diff --git a/packages/python/tests/test_parse_e2e.py b/packages/python/tests/test_parse_e2e.py
new file mode 100644
index 0000000..0648208
--- /dev/null
+++ b/packages/python/tests/test_parse_e2e.py
@@ -0,0 +1,140 @@
+"""E2E tests for LiteParse.parse() — validates Python types match CLI output."""
+
+import json
+from pathlib import Path
+
+import pytest
+
+from liteparse import (
+ LiteParse,
+ ParseResult,
+ ParsedPage,
+ TextItem,
+ BoundingBox,
+ ParseError,
+ CLINotFoundError,
+)
+
+
+class TestParseBasic:
+ """Basic parse functionality and output structure."""
+
+ def test_parse_returns_parse_result(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.parse(invoice_pdf, ocr_enabled=False)
+ assert isinstance(result, ParseResult)
+
+ def test_parse_result_has_pages(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.parse(invoice_pdf, ocr_enabled=False)
+ assert len(result.pages) > 0
+ assert result.num_pages == len(result.pages)
+
+ def test_parse_result_has_text(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.parse(invoice_pdf, ocr_enabled=False)
+ assert isinstance(result.text, str)
+ assert len(result.text) > 0
+
+ def test_parse_result_has_json(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.parse(invoice_pdf, ocr_enabled=False)
+ assert result.json is not None
+ assert "pages" in result.json
+
+
+class TestParsedPageStructure:
+ """Validate ParsedPage fields match CLI output."""
+
+ def test_page_fields(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.parse(invoice_pdf, ocr_enabled=False)
+ page = result.pages[0]
+ assert isinstance(page, ParsedPage)
+ assert isinstance(page.pageNum, int)
+ assert page.pageNum >= 1
+ assert isinstance(page.width, (int, float))
+ assert isinstance(page.height, (int, float))
+ assert page.width > 0
+ assert page.height > 0
+ assert isinstance(page.text, str)
+
+ def test_page_has_text_items(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.parse(invoice_pdf, ocr_enabled=False)
+ page = result.pages[0]
+ assert len(page.textItems) > 0
+
+ def test_text_item_fields(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.parse(invoice_pdf, ocr_enabled=False)
+ item = result.pages[0].textItems[0]
+ assert isinstance(item, TextItem)
+ assert isinstance(item.text, str)
+ assert isinstance(item.x, (int, float))
+ assert isinstance(item.y, (int, float))
+ assert isinstance(item.width, (int, float))
+ assert isinstance(item.height, (int, float))
+ # fontName and fontSize may be None or present
+ if item.fontName is not None:
+ assert isinstance(item.fontName, str)
+ if item.fontSize is not None:
+ assert isinstance(item.fontSize, (int, float))
+
+ def test_bounding_box_fields(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.parse(invoice_pdf, ocr_enabled=False, precise_bounding_box=True)
+ page = result.pages[0]
+ assert len(page.boundingBoxes) > 0
+ bbox = page.boundingBoxes[0]
+ assert isinstance(bbox, BoundingBox)
+ assert isinstance(bbox.x1, (int, float))
+ assert isinstance(bbox.y1, (int, float))
+ assert isinstance(bbox.x2, (int, float))
+ assert isinstance(bbox.y2, (int, float))
+
+
+class TestParseOptions:
+ """Test that CLI options are correctly forwarded."""
+
+ def test_target_pages(self, parser: LiteParse, invoice_pdf: Path):
+ # invoice.pdf has 2 pages — parse only page 1
+ result = parser.parse(invoice_pdf, ocr_enabled=False, target_pages="1")
+ assert result.num_pages == 1
+ assert result.pages[0].pageNum == 1
+
+ def test_max_pages(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.parse(invoice_pdf, ocr_enabled=False, max_pages=1)
+ assert result.num_pages == 1
+
+ def test_no_precise_bbox(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.parse(invoice_pdf, ocr_enabled=False, precise_bounding_box=False)
+ assert isinstance(result, ParseResult)
+ # With no precise bbox, boundingBoxes should be empty
+ for page in result.pages:
+ assert len(page.boundingBoxes) == 0
+
+ def test_get_page_helper(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.parse(invoice_pdf, ocr_enabled=False)
+ page1 = result.get_page(1)
+ assert page1 is not None
+ assert page1.pageNum == 1
+ assert result.get_page(999) is None
+
+ def test_multi_page_text_joined(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.parse(invoice_pdf, ocr_enabled=False)
+ assert result.num_pages == 2
+ # result.text should be the join of all page texts
+ expected = "\n\n".join(p.text for p in result.pages)
+ assert result.text == expected
+
+
+class TestParseErrors:
+ """Test error handling."""
+
+ def test_file_not_found(self, parser: LiteParse):
+ with pytest.raises(FileNotFoundError):
+ parser.parse("/nonexistent/file.pdf")
+
+ def test_cli_not_found(self):
+ parser = LiteParse(cli_path="/nonexistent/liteparse")
+ # subprocess raises FileNotFoundError when the binary doesn't exist
+ with pytest.raises((ParseError, FileNotFoundError, OSError)):
+ parser.parse(Path(__file__)) # any existing file
+
+ def test_timeout(self, parser: LiteParse, invoice_pdf: Path):
+ # Extremely short timeout should fail
+ with pytest.raises(TimeoutError):
+ parser.parse(invoice_pdf, timeout=0.001)
diff --git a/packages/python/tests/test_screenshot_e2e.py b/packages/python/tests/test_screenshot_e2e.py
new file mode 100644
index 0000000..75f9c95
--- /dev/null
+++ b/packages/python/tests/test_screenshot_e2e.py
@@ -0,0 +1,95 @@
+"""E2E tests for LiteParse.screenshot() — validates Python types match CLI output."""
+
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from liteparse import (
+ LiteParse,
+ ScreenshotBatchResult,
+ ScreenshotResult,
+ ImageFormat,
+ ParseError,
+)
+
+
+class TestScreenshotBasic:
+ """Basic screenshot functionality."""
+
+ def test_screenshot_returns_batch_result(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.screenshot(invoice_pdf)
+ assert isinstance(result, ScreenshotBatchResult)
+
+ def test_screenshot_has_screenshots(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.screenshot(invoice_pdf)
+ assert len(result) > 0
+ assert len(result.screenshots) > 0
+
+ def test_screenshot_result_fields(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.screenshot(invoice_pdf)
+ ss = result.screenshots[0]
+ assert isinstance(ss, ScreenshotResult)
+ assert isinstance(ss.page_num, int)
+ assert ss.page_num >= 1
+ assert isinstance(ss.image_path, str)
+ assert Path(ss.image_path).exists()
+
+ def test_screenshot_output_dir(self, parser: LiteParse, invoice_pdf: Path):
+ with tempfile.TemporaryDirectory() as tmpdir:
+ result = parser.screenshot(invoice_pdf, output_dir=tmpdir)
+ assert result.output_dir == tmpdir
+ # Files should be in the specified directory
+ for ss in result.screenshots:
+ assert ss.image_path.startswith(tmpdir)
+
+ def test_screenshot_png_format(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.screenshot(invoice_pdf, image_format=ImageFormat.PNG)
+ for ss in result.screenshots:
+ assert ss.image_path.endswith(".png")
+
+ def test_screenshot_jpg_format(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.screenshot(invoice_pdf, image_format="jpg")
+ for ss in result.screenshots:
+ assert ss.image_path.endswith(".jpg")
+
+
+class TestScreenshotOptions:
+ """Test screenshot options are forwarded correctly."""
+
+ def test_target_pages(self, parser: LiteParse, invoice_pdf: Path):
+ # invoice.pdf has 2 pages — screenshot only page 1
+ result = parser.screenshot(invoice_pdf, target_pages="1")
+ assert len(result) == 1
+ assert result.screenshots[0].page_num == 1
+
+ def test_load_bytes(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.screenshot(invoice_pdf, load_bytes=True)
+ for ss in result.screenshots:
+ assert ss.image_bytes is not None
+ assert len(ss.image_bytes) > 0
+
+ def test_no_load_bytes(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.screenshot(invoice_pdf, load_bytes=False)
+ for ss in result.screenshots:
+ assert ss.image_bytes is None
+
+ def test_get_page_helper(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.screenshot(invoice_pdf)
+ page1 = result.get_page(1)
+ assert page1 is not None
+ assert page1.page_num == 1
+ assert result.get_page(999) is None
+
+ def test_iterable(self, parser: LiteParse, invoice_pdf: Path):
+ result = parser.screenshot(invoice_pdf)
+ pages = list(result)
+ assert len(pages) == len(result)
+
+
+class TestScreenshotErrors:
+ """Test error handling."""
+
+ def test_file_not_found(self, parser: LiteParse):
+ with pytest.raises(FileNotFoundError):
+ parser.screenshot("/nonexistent/file.pdf")