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.pyindex 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 documentsocr_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 parsetarget_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 textpreserve_very_small_text: Whether to preserve very small text+ password: Password for encrypted/protected documentstimeout: 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 documentsocr_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 filedpi: DPI for renderingprecise_bounding_box: Whether to compute precise bounding boxesrecursive: Whether to recursively search subdirectoriesextension_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 batchReturns:@@ -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 renderingimage_format: Image format ("png" or "jpg")+ password: Password for encrypted/protected documentsload_bytes: If True, load image bytes into ScreenshotResult objectstimeout: 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.pyindex d04308a..976e86b 100644--- a/packages/python/liteparse/types.py+++ b/packages/python/liteparse/types.py@@ -29,14 +29,11 @@ class BoundingBox:@dataclassclass TextItem:"""Individual text item extracted from a document."""- str: str+ text: strx: floaty: floatwidth: floatheight: float- w: float- h: float- r: float # rotationfontName: Optional[str] = NonefontSize: Optional[float] = Nonediff --git a/packages/python/pyproject.toml b/packages/python/pyproject.tomlindex 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 = truewarn_return_any = truewarn_unused_ignores = true--[tool.pytest.ini_options]-asyncio_mode = "auto"diff --git a/packages/python/tests/__init__.py b/packages/python/tests/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/packages/python/tests/conftest.py b/packages/python/tests/conftest.pynew file mode 100644index 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 pdiff --git a/packages/python/tests/test_batch_e2e.py b/packages/python/tests/test_batch_e2e.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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")