Metadata-Version: 2.4
Name: docvortex
Version: 0.3.0
Summary: A fast, multi-format document parsing and conversion engine
License-Expression: MIT
Project-URL: Repository, https://github.com/myhloli/DocVortex
Project-URL: Issues, https://github.com/myhloli/DocVortex/issues
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: click>=8.1.7
Requires-Dist: loguru>=0.7.2
Requires-Dist: numpy>=1.21.6
Requires-Dist: pillow>=11.0.0
Requires-Dist: pypdfium2<6,>=5.10.1
Requires-Dist: pypdf>=5.6.0
Requires-Dist: pydantic<3,>=2.12.5
Requires-Dist: metafile-render<1.0.0,>=0.3.0
Requires-Dist: ftfy<7,>=6.3.1
Requires-Dist: fonttools<5,>=4
Requires-Dist: beautifulsoup4<5,>=4.13.5
Requires-Dist: lxml<7,>=4
Requires-Dist: nh3<0.4,>=0.3.6
Requires-Dist: python-docx<2,>=1.2.0
Requires-Dist: pypptx-with-oxml<2,>=1.0.3
Requires-Dist: mammoth<2,>=1.11.0
Requires-Dist: openpyxl<4,>=3.1.5
Requires-Dist: olefile<1,>=0.47
Requires-Dist: pylatexenc<3,>=2.10
Requires-Dist: latex2mathml<4,>=3.81.0
Requires-Dist: mathml2omml==0.0.2
Requires-Dist: resvg_py<0.6,>=0.5.0
Requires-Dist: reportlab
Requires-Dist: ziamath<0.14,>=0.13
Requires-Dist: magika<1.1.0,>=0.6.2
Requires-Dist: opencv-python>=4.11.0.86
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: markdown; extra == "test"
Requires-Dist: jsonschema<5,>=4; extra == "test"
Provides-Extra: dev
Requires-Dist: ruff==0.14.2; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file


![DocVortex overview: native document inputs flow through a unified document model to Markdown, HTML, LaTeX, DOCX, EPUB, PDF and structured content.](https://gcore.jsdelivr.net/gh/myhloli/DocVortex@main/docs/images/docvortex-overview.jpg)

# DocVortex

A fast, multi-format document parsing and conversion engine.

DocVortex provides a complete, standalone document pipeline:

```text
Document -> Unified Intermediate Representation -> Render / Export
```

Native inputs include text PDFs, DOC/DOCX, PPT/PPTX, XLS/XLSX, RTF, ODT/ODS/ODP,
EPUB, HTML, OFD and CSV. Output formats include Markdown, HTML, LaTeX, DOCX,
EPUB, PDF and structured content. 

Native parsing runs without OCR or VLM inference services.
PDF classification is an explicit document operation; native analysis does not
silently classify the document or select another inference backend.

## Install

```bash
pip install docvortex
docvortex convert report.pdf --format markdown --output output/report.md
docvortex classify report.pdf
```

Python 3.10–3.14 is supported. Native parsing does not require OCR/VLM inference
services. 

## Parse once, export many times

```python
import docvortex

result = docvortex.parse("report.pdf", keep_model_json=True)
result.export("output/report.md", output_format="markdown")
result.export("output/report.docx", output_format="docx")
result.export("output/report.epub", output_format="epub")
result.save_bundle("output/report.bundle")

# This works after the source document and its parsing process are gone.
restored = docvortex.load_bundle("output/report.bundle")
restored.export("output/report.pdf", output_format="pdf")
```

Bundles contain `manifest.json`, `middle.json`, optional `model.json`, and image
assets. The loader verifies asset hashes. Missing external assets must be supplied
before saving a portable bundle. Existing files are protected unless the caller
explicitly sets `overwrite=True`.

## Stage APIs

```python
from docvortex.api import analyze, postprocess, render

analysis = analyze("report.pdf", page_range="1-5")
result = postprocess(analysis)
artifact = render(result.middle_json, "docx", assets=result.assets)
artifact.write("output/report.docx")
```

The stage API lives in `docvortex.api`. Root-level conveniences include `parse`,
`analyze`, `convert`, `postprocess_document`, and `render_artifact`. The
`docvortex.render` package also exposes the low-level renderers and their original
string, bytes, dictionary, or list return values.

PDF page selections use `1-5`, `r1` and `all`; other native formats are parsed as
whole documents. A caller-owned `PDFDocument` can be passed to `analyze` or `parse`
and remains open afterward.

## Page images and embedded assets

```python
from docvortex.assets import parse_image_data_uri_strict, transcode_image
from docvortex.content.tree import iter_image_payloads
from docvortex.document.pdf import PDFDocument

with PDFDocument("report.pdf") as document:
    image = document.render_image(0, bbox=(0.1, 0.2, 0.8, 0.7), image_format="png")
# image.data, image.width, image.height, image.mime_type and image.extension
# remain available after the document closes.
```

`render_image` accepts zero-based page indices, optional normalized bounding boxes
and `jpeg` (default), `png` or `webp` output. Omitting `bbox` renders the whole page.
Crops are encoded directly to the requested format. `crop_image` continues to
return JPEG bytes. Image sources opened with `PDFDocument.from_image` retain the
existing image-to-PDF conversion behavior.

`docvortex.assets` exposes immutable `ImageArtifact` and `ImageFormat` contracts.
`parse_image_data_uri_strict(uri)` validates embedded image bytes and returns
`(data, extension)`; `transcode_image(data, image_format="png")` returns an
`ImageArtifact`. These operations do not fetch URLs or resolve filesystem paths,
and transcoding does not add SVG rasterization support.
`iter_image_payloads(block)` yields the current node, if it carries an image,
then traverses its children depth first without modifying the document tree.

## Explicit PDF classification

```python
from docvortex.document.pdf import PDFDocument

with PDFDocument("report.pdf") as document:
    mode = document.classify()  # "txt" or "ocr"; no inference is started
    if mode == "txt":
        result = docvortex.parse(document)
```

Native analysis trusts the caller's choice and does not classify automatically.
Applications can use the classification result to select their own OCR or
inference service when a document requires it.

DocVortex JSON uses schema identity `docvortex.model` or `docvortex.middle`, schema
version `2.0`, and required `metadata.file_suffix` / `metadata.producer`. Definitions are in `schemas/`.
Application-specific metadata belongs in `extensions`. See the
[shared JSON protocol and migration guide](docs/JSON_PROTOCOL.md) and the
[compatibility guide](docs/COMPATIBILITY.md) for existing application integrations
and historical data formats. The [HTML protocol](docs/HTML_PROTOCOL.md) describes
DocVortex markers and semantic round trips.

## Scope and development

PDF output is a semantic reflow of the document, not a lossless reproduction of
the original page drawing instructions. Input support for PPTX/XLSX does not imply
PPTX/XLSX output support. Rust implementation work is a future stage behind these
public data and processing boundaries.

```bash
uv venv
uv pip install -e ".[test,dev]"
uv run --no-project python -m pytest -q
uv run --no-project ruff check src
uv run --no-project ruff format --check src
uv build
```

DocVortex project code is licensed under the [MIT License](LICENSE.md).

See [rendering ownership](docs/RENDER_OWNERSHIP.md) for the seven engine targets,
MinerU Content List integration and public fragment helpers.

## Read source metadata without parsing the body

```python
from docvortex import extract_metadata

inspection = extract_metadata("report.pdf")
print(inspection.metadata.document.title)
print(inspection.metadata.document.authors)
```

All 15 native document formats support this API. Normal parsing also carries these properties in
`metadata.document`, preserving the original PDF properties across page selections. See the
[field definitions, format matrix, and compatibility notes](docs/METADATA.md).


### Python 3.14 and text joining (0.3.0)

DocVortex supports ordinary CPython 3.10–3.14. Physical text lines are joined by deterministic Unicode boundary rules, with URL and dehyphenation safeguards. Language detection models and the fast-langdetect / fasttext-predict dependencies are no longer required.

The shared `resolve_text_line_boundary` and `merge_text_line_contents` helpers no longer accept `block_language`; `detect_lang` has been removed. Hosts should call the shared boundary helpers directly. OCR language selection and Magika code-language recognition are unchanged.
