Getting Started
Python document conversion library
Add typed DOCX, PDF, HTML, Markdown, YAML, JSON, and image conversion to Python applications with engine-neutral requests, results, batches, and diagnostics.
Library overview
The public API uses engine-neutral typed models. Choose the smallest entry point that meets the integration need.
| Entry point | Use it for |
|---|---|
| ConversionRequest.from_source | Infer and validate source format from a path |
| convert(request) | Run one conversion and receive ConversionResult |
| DocumentConversionService | Inject engines or use service methods directly |
| convert_batch(requests) | Run sequential, failure-isolated conversions |
| probe_engines() | Discover renderer availability and annotation capabilities |
| result.to_dict() | Produce stable JSON-compatible result data |
Single conversion
ConversionRequest.from_source validates the allowlisted extension and infers the source format. convert returns a ConversionResult rather than raising for ordinary conversion failures, so inspect success and error before reading artifacts. ConversionError is reserved for invalid requests and related contract errors.
from pathlib import Path
from gordon_doc_converter import ConversionRequest, convert
result = convert(ConversionRequest.from_source(Path('report.docx')))
if not result.success:
raise RuntimeError(result.error.message if result.error else 'conversion failed')
print(result.artifacts[0].path)Options and strict policy
Use ConversionOptions to choose output paths, overwrite behaviour, timeout, deployment mode, an explicit engine, annotation handling, metadata detail, and image settings. EngineName is strict: an unavailable explicitly chosen engine produces a diagnosable failure rather than a silent alternative. ArtifactType can request PDF, DOCX, ODT, HTML, Markdown, YAML, JSON, or page images where the route supports it.
from pathlib import Path
from gordon_doc_converter import (
ArtifactType, ConversionOptions, ConversionRequest, convert,
)
request = ConversionRequest.from_source(
Path('report.docx'),
artifacts=(ArtifactType.YAML, ArtifactType.JSON),
options=ConversionOptions(output_path=Path('report')),
)
result = convert(request)Batches, probes, and result handling
DocumentConversionService supports dependency injection for engines and environment-aware orchestration. convert_batch processes requests sequentially and keeps failures isolated. probe_engines returns EngineProbeResult entries with availability, version, supported revision modes, and comment modes. Results serialize through to_dict() to stable JSON-compatible primitives for logs or APIs; do not log document contents or sensitive paths.
from gordon_doc_converter import DocumentConversionService
service = DocumentConversionService()
for probe in service.probe_engines():
print(probe.engine, probe.available, probe.version)
results = service.convert_batch(requests)
payload = [result.to_dict() for result in results]