Metadata-Version: 2.4
Name: udoc
Version: 0.1.0a1
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
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 :: Rust
Classifier: Topic :: Office/Business
Classifier: Topic :: Text Processing
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Dist: pandas>=2.0 ; extra == 'all'
Requires-Dist: pyarrow>=14 ; extra == 'all'
Requires-Dist: pyarrow>=14 ; extra == 'arrow'
Requires-Dist: pandas>=2.0 ; extra == 'pandas'
Provides-Extra: all
Provides-Extra: arrow
Provides-Extra: pandas
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Summary: Dependency free extraction from documents.
Keywords: pdf,docx,xlsx,pptx,office,extraction,text-extraction,documents,ocr
Home-Page: https://github.com/newelh/udoc
Author-email: newel <me@newel.dev>
License: Apache-2.0 OR MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/newelh/udoc/blob/main/CHANGELOG.md
Project-URL: Documentation, https://newelh.github.io/udoc
Project-URL: Homepage, https://github.com/newelh/udoc
Project-URL: Issues, https://github.com/newelh/udoc/issues
Project-URL: Repository, https://github.com/newelh/udoc

# udoc

Dependency free extraction from documents.  

Extract text, tables, JSON, or rendered pages. CLI, Python Bindings, Pure Rust. No external parsers, libraries, or system packages are required. Provides [hooks](https://newelh.github.io/udoc/hooks/) for OCR, layout detection, and entity extraction. Permissively licensed as dual MIT / Apache-2.0.

Supports PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, ODT, ODS, ODP, RTF, and Markdown.

The full hosted manual lives at <https://newelh.github.io/udoc/>.

---

Try it out using [uv](https://docs.astral.sh/uv/), no install required:

```bash
curl -sL https://arxiv.org/pdf/1706.03762 \
  | uvx udoc - | grep -A 18 '^Abstract'
```

## Installation

```bash
# uv
uv add udoc

# pip
pip install udoc

# cargo (coming soon)
```

To build from source, see the [compile guide](https://newelh.github.io/udoc/compiling/).

## Highlights

- **One `Document` model across formats.** A content spine of `Block` and `Inline` nodes, plus optional [presentation, relationships, and interactions overlays](https://newelh.github.io/udoc/reference/document-model/). Disable any overlay via `Config`.
- **Legacy binary Office.** Native parsers for `.doc`, `.xls`, and `.ppt`. Per-format details in the [format guides](https://newelh.github.io/udoc/formats/).
- **Streaming page-by-page.** The `Extractor` defers per-page work. A 10 GB PDF does not have to fit in memory.
- **Typed diagnostics.** Recoverable issues become structured warnings filterable by `kind`. Examples: font fallbacks, malformed `xref`, stream-length mismatches.
- **Hooks for OCR, layout, and annotation.** [JSONL protocol](https://newelh.github.io/udoc/hooks/) for Tesseract, cloud OCR APIs, DocLayout-YOLO, GLM-OCR, vision-language models, NER, or any subprocess that reads JSON line-by-line.
- **LLM tool use.** [Agent instructions](https://newelh.github.io/udoc/agents/) — a paste-into-context page describing udoc's CLI to assistants.

## Usage

### CLI

```bash
udoc paper.pdf                     # text to stdout
udoc -j paper.pdf                  # full document as JSON
udoc -J paper.pdf                  # streaming JSONL (one record per page)
udoc -t spreadsheet.xlsx           # tables only as TSV
udoc -p 1-5,10 paper.pdf           # page range
udoc render paper.pdf -o ./pages   # rasterise PDF pages to PNG
cat paper.pdf | udoc -             # read from stdin
```

A few real-world piping recipes:

```bash
curl -sL https://arxiv.org/pdf/1706.03762 | udoc - | head -40
udoc paper.pdf | grep -i 'attention'
udoc -J docs/*.pdf | jq '.metadata.title'
```

Plain text on stdout. Structured output on flags. Stderr is silent unless you pass `-v`. The full flag list lives in the [CLI reference](https://newelh.github.io/udoc/cli/).

### Python

```python
import udoc

# One-shot extraction. Format detected from magic bytes.
doc = udoc.extract("paper.pdf")
print(doc.metadata.title)
for block in doc.blocks():
    print(block.text)

# Stream page by page; large documents do not have to fit in memory.
with udoc.stream("large.pdf") as ext:
    for i in range(len(ext)):
        print(f"page {i}: {ext.page_text(i)[:80]}")

# In-memory bytes with options.
with open("encrypted.pdf", "rb") as f:
    doc = udoc.extract_bytes(f.read(), password="secret")
```

PDF table detection and reading order are heuristic. Born-digital documents with clean ruling and standard column flow extract cleanly out of the box; the [PDF format guide](https://newelh.github.io/udoc/formats/pdf/) covers the failure modes and when to attach a [layout-detection or OCR hook](https://newelh.github.io/udoc/formats/pdf/#triggering-ocr).

The [Guide](https://newelh.github.io/udoc/library/) walks through configuration, overlays, diagnostics, chunking, and batch processing. The [Python Library reference](https://newelh.github.io/udoc/reference/python/) lists every function, class, and exception.

### Rust

```rust
let doc = udoc::extract("paper.pdf")?;
println!("{:?}", doc.metadata.title);
for block in &doc.content {
    println!("{}", block.text());
}
```

The Rust facade mirrors the Python shape. `Document` is `udoc_core::document::Document`; iteration is by direct field access (`doc.content`, `doc.metadata`, `doc.images`). The [Rust Library reference](https://newelh.github.io/udoc/reference/rust/) covers the facade, the per-format backends, configuration presets, diagnostics, and the trait that backends implement.

## Status

This is the initial alpha release of udoc. APIs and outputs are subject
to change. Bugs, ergonomic suggestions, and format quirks are welcome on
the [issue tracker](https://github.com/newelh/udoc/issues).

