eDocAPI Python Framework Documentation

Overview

eDocAPI is a Python toolkit for practical document workflows. Convert, extract, recognize, compress, and merge documents through one consistent interface — as a library, CLI, or lightweight ASGI application.

Version 0.2.0 focuses on predictable failures, safer uploads, and release reliability.

Install

pip install edocapi

Python

3.10 – 3.13

License

MIT

Why I’m building eDocAPI

I’m building eDocAPI so Python developers can take a document from upload to useful text or a converted file through one clear workflow. I focus on the details that matter in real use: preserving page structure, handling uploads carefully, and making OCR easier to configure. I’ll keep refining these parts and add capabilities as practical use shows what should come next.

— Emmanuel Emmanuel Etim

Highlights in 0.2.0

What this release emphasizes for everyday document work.

One document toolkit – convert, extract, recognize, compress, and merge through a consistent Python interface.
Structured recognition – optional PaddleOCR adds page layout, table, and formula recognition.
Careful file handling – uploads are validated, size-limited, and stored with controlled temporary-file cleanup.
Readable document output – DOCX-to-PDF preserves headings, page breaks, table widths, and repeating table headers.
Tools for developers – Python library, command-line tools, ASGI application, and interactive dashboard.

Full changelog: Release notes 0.2.0 (PDF)

Quick start (library)

Work with documents in a few lines of Python.

from edocapi import Document

# From a file
doc = Document("report.docx")
pdf = doc.to_pdf()
text = doc.extract_text()
info = doc.info()

# From in-memory content
doc = Document.markdown("# Hello\n\nWorld")
pdf = doc.to_pdf()

# OCR — embedded PDF text is read directly; scanned pages need OCR extras
# Image OCR and scanned-page OCR: pip install edocapi[ml]
text = Document("scan.png").ocr(lang="eng")

# Structured OCR (layout, tables, formulas)
# pip install edocapi[structured-ocr]  (Python ≤ 3.13)
text = Document("exam.pdf").ocr(engine="paddle")

# Merge PDFs
merged = Document.merge(["a.pdf", "b.pdf"])

# Compress
small = Document("large.pdf").compress(target_size=500_000)

Formula results from Paddle are represented as Markdown/LaTeX where recognized. Choosing Paddle runs full layout and formula reconstruction, including text-based PDFs whose native text cannot represent stacked equations.

Quick start (API server)

Build a small document API with the App class.

# main.py
from edocapi import App, Document

# Files up to 50MB by default
app = App()

# Smaller limit for a particular service (max 50MB)
uploads_app = App(max_file_size="10MB")

@app.post("/convert")
def convert(file):
    return Document(file).to_pdf()

@app.post("/extract")
def extract(file):
    return {"text": Document(file).extract_text()}

pip install edocapi[server]
uvicorn main:app --reload

Open http://127.0.0.1:8000 for the interactive developer dashboard. Supported Python versions are 3.10–3.13. Optional renderers and OCR engines are installed through documented extras; missing extras produce framework errors or documented basic-renderer fallbacks.

The ASGI /ocr route is disabled by default; enable with App(enable_ocr=True).

Upload limits

App accepts files up to 50MB by default. Set max_file_size for a smaller limit. Integer values are bytes; strings may use KB or MB.

from edocapi import App

app = App(max_file_size="10MB")

The framework enforces 50MB as the highest permitted per-file limit. The total request body has an independent 100MB default via max_request_size.

413 — oversized file or request body
400 — missing uploads or invalid documents
415 — unsupported types or signature mismatches
500 — generic response for unexpected errors (details stay in server logs)

Rate limits

Set a default rolling-window limit per client, then stricter limits on expensive routes. Built-in /health is exempt.

from edocapi import App

app = App()
app.limits(100, per="minute")

@app.post("/convert", limit="10/minute")
def convert(file):
    ...

@app.post("/ocr", limit="3/minute")
def ocr(file):
    ...

Over-limit requests receive 429 and a Retry-After header. Client identity comes from the ASGI connection IP; forwarded headers are not trusted. Limits are process-local — use a shared store at the deployment layer for multi-worker limits.

Troubleshooting DOCX uploads

A valid DOCX can be rejected when its filename fails eDocAPI's filename validation.

Error

Uploading eDocAPI_Developer_Course_0.2.0.docx returned:

WARNING  edocapi  eDocAPI error: Invalid filename detected.
INFO:     ... "POST /convert HTTP/1.1" 415 Unsupported Media Type

Cause

The DOCX file was valid. In this case, the version dots in the filename (0.2.0) triggered filename validation. Renaming the same file made the upload succeed, confirming that the filename caused the rejection.

Solution

Rename the file to a simple name with one .docx extension, for example eDocAPI_Developer_Course.docx. Avoid version numbers with periods and repeated extensions such as .docx.docx. Rename the file only; its document contents and MIME type do not need to change. If the problem persists, check the filename sent with the multipart upload and the exact server error.

Supported formats

Operations for each input type (valid, non-empty documents; optional packages as noted).

Input	to_pdf	extract	ocr	compress	merge	to_images
PDF	Yes	Yes	Yes¹	Yes	Yes²	Yes³
DOCX	Yes	Yes	No	No	No	No
HTML / HTM	Yes⁴	Yes	No	No	No	No
Markdown	Yes⁴	Yes⁷	No	No	No	No
TXT	Yes	Yes	No	No	No	No
JPEG / PNG / WebP	Yes	Yes⁵	Yes⁵	Yes⁶	No	No

PDF extract_text() needs no OCR extra. Scanned pages with Tesseract need edocapi[ml] (+ Tesseract); rendering may need edocapi[pdf-images]. Paddle needs edocapi[structured-ocr].
merge() accepts PDF inputs only.
to_images() needs edocapi[pdf-images] and Poppler.
Built-in basic renderer; edocapi[html] enables WeasyPrint. Local/remote resources are blocked.
Image extract/OCR via Tesseract requires [ml]; Paddle uses [structured-ocr].
Target-size PNG compression may output WebP or JPEG.
Markdown extract returns source including markers (not plain-text conversion).

Optional extras

Install only what you need.

pip install edocapi[html]           # HTML/Markdown → PDF (WeasyPrint)
pip install edocapi[pdf-images]     # PDF → images (pdf2image)
pip install edocapi[ml]             # OCR + OpenCV pre-processing
pip install edocapi[structured-ocr] # PaddleOCR (Python ≤ 3.13)
pip install edocapi[all]            # everything
pip install edocapi[server]         # uvicorn

PaddleOCR note

Advanced pipeline needs Python 3.13 or earlier (Windows). Prefetch models before serving: edocapi prefetch-ocr --lang en. One-time download can be several GB. Chart recognition is off by default; set EDOCAPI_PADDLE_CHART_RECOGNITION=1 to enable.

If Hugging Face is slow: edocapi prefetch-ocr --lang en --model-source bos --disable-model-source-check

Security highlights

Built-in defaults aimed at safer document APIs.

Filenames sanitized (basename only; dangerous characters stripped).
Magic-byte verification prevents extension spoofing.
50MB per-file ceiling, with configurable file-size and file-count limits.
Multipart uploads stream to temporary files; independent max_request_size (100MB default).
Collision-resistant temporary names; cleanup confined to registered paths under the storage root.
Dashboard metadata HTML-escaped; route templates validated; response filenames encoded safely; baseline browser security headers.
Temporary files isolated and cleaned up automatically.
Document contents validated and processed as data before they enter a workflow.
HTML/Markdown/DOCX PDF rendering blocks local and remote resource access.
Generic internal errors to clients; diagnostics stay in server logs.

CLI

Command-line tools for everyday conversion and inspection.

edocapi --version
edocapi convert report.docx -o report.pdf
edocapi extract report.pdf
edocapi info image.png
edocapi ocr scan.png --lang eng
edocapi ocr exam.pdf --engine paddle
edocapi prefetch-ocr --lang en
edocapi compress large.pdf --target 500KB

PDF compression removes duplicate objects and compresses content streams. With a target size, embedded images are downsampled while selectable text is preserved when possible. If needed, pages may be rasterized as JPEG (no longer selectable). API responses report target success with the X-Edocapi-Compression-Target-Met header.

Document workflow details (v0.2.0)

Layout, dashboard, and reliability behavior that ships in this version.

DOCX-to-PDF uses ReportLab’s paginated layout engine (core dependency).
DOCX conversion preserves centered cover titles, heading hierarchy, paragraph order, source table widths, and explicit page breaks.
Contents pages use readable spacing and indentation for main sections and subsections.
Tables have visible borders, dark readable text, emphasized first-column labels, and repeating header rows across page breaks.
Interactive dashboard: feature summary and a single /health card for both GET and POST.
Dashboard “Try it” responses, errors, and file previews appear in a modal without leaving the page.
Optional html extra adds HTML/Markdown PDF rendering via WeasyPrint.
Missing, empty, encrypted, corrupt, and unsupported documents return stable framework errors.
HTML/Markdown/DOCX PDF rendering blocks local and remote resource access.
Multipart uploads stream to managed temporary files under a separate total-request limit.