pydoccraft

pydoccraft 0.3.0 is an Apache-2.0 Python/Rust package for eager, in-process structured extraction, rendering, and semantic conversion of PDF, DOCX, and PPTX files. It exposes the compatible doc_ex PyMuPDF-style API and uses pinned PdfCraft, WordCraft, and DeckCraft library crates—without external executables, runtime downloads, networking, cloud credentials, or OCR.

Install

python -m pip install pydoccraft

The wheel contains the private doc_ex._core native extension. No office suite, Pandoc, or Craft CLI is required.

Quick start

from pathlib import Path
import doc_ex

with doc_ex.open("report.pdf") as document:
    print(document.page_count)
    print(document[0].get_text())
    print(document[0].get_text("markdown"))
    print(document[0].get_links())
    print(document[0].find_tables())
    Path("page.png").write_bytes(document[0].get_pixmap(dpi=144))
    Path("report.docx").write_bytes(document.convert("docx"))

Path("report.pdf").write_bytes(doc_ex.convert("report.docx", "pdf"))
Path("slides.pdf").write_bytes(doc_ex.convert("slides.pptx", "pdf"))

Document supports context management, iteration, integer and negative indexing, load_page, page_count, metadata, Markdown, PNG rendering, conversion, and idempotent close. Page.number is zero-based. Returned Block, Table, Link, and Image objects own their extracted data.

Supported operations

PDF table detection is conservative. PDF links retain destinations and geometry; unambiguous single-line and contiguous multiline labels have exact character offsets. Ambiguous regions remain unresolved. DOCX computed pagination cannot split one automatically wrapped paragraph into exact normalized page slices. PPTX exposes URL links but not every PowerPoint action. Conversion uses upstream semantic exporters and is not pixel-perfect.

Render a page at a chosen DPI

The same API works for PDF pages, DOCX layout pages, and PPTX slides:

from pathlib import Path
import doc_ex

with doc_ex.open("report.docx") as document:  # also .pdf or .pptx
    Path("page-1.png").write_bytes(document.render_page(0, dpi=300))
    # Equivalent: document[0].get_pixmap(dpi=300)
    Path("detail.png").write_bytes(document.render_page(0, dpi=300, clip=(36, 36, 144, 72)))

Indexes are zero-based; negative indexes are supported. DPI defaults to 144 and must be finite and between 1 and 1200, subject to output-size limits. Both methods return PNG bytes. Optional clip=(x, y, width, height) selects a region in displayed-page points. DOCX pagination follows WordCraft layout and may differ from Microsoft Word. See rendering details.

Version 0.3.0 adds native authoring through doc_ex.new("docx" | "pdf" | "pptx"), including text, tables, images, backgrounds, explicit saving and independent copies. See the authoring API for examples, the supported edit profile and current limits. Earlier releases, such as 0.2.1, do not include these additions.

The expanded roadmap covers Open XML feature parity, styles, sections, templates, review features and safe editing. The design and reference crosswalk keeps ArtCraft libraries as the only document backend. Unchecked coverage remains incomplete even where an initial slice is implemented.

The coverage checklist is consolidated into 14 connected workstreams, with upstream contribution candidates distinguished from existing library support. Reports, watermarks, templates and batches should compose a small core API wherever possible.

Track the work in the GitHub Roadmap project.

Documentation

Browse the documentation website for guides, examples and the roadmap. It follows main; unreleased features remain labeled separately from published packages.

• Python API
• Native authoring
• Six runnable cookbook workflows
• Formats, rendering, and conversion
• Safety and resource behavior
• Dependencies, licensing, and attribution
• PDF performance versus PyMuPDF
• Development and release validation
• Feature roadmap and TODOs
• Proposed Python authoring API and Open XML crosswalk
• Canonical workstreams and dependencies
• Upstream ownership and pinned-source evidence

Development

cargo fmt --all -- --check
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings
maturin build --release --locked --out dist
python -m unittest discover -s tests -v

Release validation must install the built wheel into a clean environment and run the suite against that installed package. Tests generate their own fixtures and require no external document tools.

Community

• Read CONTRIBUTING.md before proposing changes.
• Ask usage questions through GitHub Discussions and report reproducible defects through GitHub Issues.
• Report vulnerabilities privately according to SECURITY.md; never attach malicious or confidential documents to public issues.
• Participation is governed by the Code of Conduct, with project decisions described in GOVERNANCE.md and support expectations in SUPPORT.md.

License

pydoccraft is licensed under Apache-2.0. Distributions include LICENSE, NOTICE, and the wheel-compatible LICENSE-THIRD-PARTY copy of the audited THIRD_PARTY_LICENSES.md inventory. Upstream dependency names identify their source and are not pydoccraft branding.

The source repository is narain1/pydoccraft. PyPI trusted publishing is configured for project pydoccraft, repository pydoccraft, workflow release.yml, and environment pypi.