Metadata-Version: 2.4
Name: document-svg
Version: 2.0.1
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Requires-Dist: pytest>=8,<10 ; extra == 'test'
Provides-Extra: test
License-File: legal/LICENSE
License-File: legal/LICENSE-MIT
License-File: legal/LICENSE-APACHE
License-File: legal/THIRD_PARTY_NOTICES.md
License-File: legal/THIRD_PARTY_LICENSES.txt
Summary: Turn PDF, Word, Excel, PowerPoint, diagram and CAD files into SVG pages from Python, locally and without Office
Keywords: svg,pdf,office,doc,dot,msdoc,legacy-word,msppt,legacy-powerpoint,kicad,kicad-pcb,eda,pcb,ppt,ooxml-strict,msproject,mspdi,gantt,visio,vsdx,vdx,email,eml,emlx,apple-mail,outlook,msg,mbox,mhtml,mht,icalendar,ics,vcalendar,vcs,vcard,vcf,tiff,dicom,dcm,dicomdir,jpeg2000,jp2,j2k,medical-imaging,webp,gif,raster,cbz,cad,cae,ifc,ifczip,su2,cfd,computational-fluid-dynamics,openfoam,foam,poly-mesh,tecplot,tecplot-ascii,ensight,ensight-gold,plot3d,plot3d-ascii,structured-grid,vrml,vrml97,netpbm,pnm,ppm,pgm,pbm,pam,dif,data-interchange-format,fasta,fastq,bioinformatics,sequence,gff,gff3,gtf,genome-annotation,bed,bedgraph,genome-interval,vcf,variant-call-format,genomics,sam,samtools,alignment,wig,wiggle,genome-signal,maf,multiple-alignment,genome-alignment,newick,phylogenetic-tree,phylo,stockholm,multiple-sequence-alignment,nexus,nexus-format,phylogenetic-data,genbank,genbank-flatfile,embl,embl-bank,uniprot,swissprot,uniprotkb,ris,research-information-systems,bibliography,spice,ngspice,circuit-netlist,eda-netlist,kicad-schematic,eeschema,legacy-kicad,kicad_sch,modern-kicad-schematic,ltspice,ltspice-asc,circuit-schematic,eagle,eagle-sch,eagle-xml,clustal,clustalw,aln,bim,industry-foundation-classes,unv,uff,finite-element,medit,mesh,meshb,geospatial,geopackage,gpkg,dbase,dbf,arff,json-ld,graphml,gexf,xgmml,gml-graph,netcdf,cdf,toml,yaml,yml,xml,properties,java-properties,bpmn,bpmn2,business-process,dmn,decision-table,decision-model,cmmn,case-management,reqif,requirements-interchange,xmi,model-interchange,sysml,configuration,geojson,geojsonseq,geojsons,json-seq,jsonseq,jsons,topojson,georss,gml,gpx,kml,kmz,shapefile,wkt,ewkt,restructuredtext,rst,org-mode,org,gettext,po,pot,bibtex,bib,subtitle,subrip,srt,webvtt,vtt,ttml,dfxp,xliff,xlf,chemical,molecule,mol,sdf,molfile,ctfile,rxn,reaction,document-conversion,e57,lidar,point-cloud,pts,ptx,xyz
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://ryusui-hiro.github.io/document-svg/start.html
Project-URL: Homepage, https://ryusui-hiro.github.io/document-svg/
Project-URL: Issues, https://github.com/ryusui-hiro/document-svg/issues
Project-URL: Node.js package, https://www.npmjs.com/package/document-svg
Project-URL: Repository, https://github.com/ryusui-hiro/document-svg

# document-svg for Python

**Turn PDF, Word, Excel, PowerPoint, diagram and CAD files into SVG pages from Python — locally, without Office.**

[Project site](https://ryusui-hiro.github.io/document-svg/) ·
[Formats](https://ryusui-hiro.github.io/document-svg/formats.html) ·
[Samples](https://ryusui-hiro.github.io/document-svg/samples.html) ·
[日本語](https://github.com/ryusui-hiro/document-svg/blob/main/README.ja.md) ·
[简体中文](https://github.com/ryusui-hiro/document-svg/blob/main/README.zh-CN.md)

`document-svg` turns a document, diagram or drawing into ordinary SVG images,
one per page, that any browser can show. It also tells you, page by page, what
it could not reproduce exactly, so you can decide whether the result is good
enough to use.

- **Files stay on your machine.** Nothing is uploaded and there is no account.
- **Nothing inside a file is run.** Macros, scripts and external links are shown or skipped, never executed.
- **No Office, no viewer, no headless browser.** One package handles Office files, PDFs, diagrams, CAD and 3D models, and many data formats.

The same converter is also available [for Node.js on npm](https://www.npmjs.com/package/document-svg)
and [for Rust, with the `docsvg` command, on crates.io](https://crates.io/crates/document-svg).

## Install

Requires Python 3.10 or newer.

```sh
python -m pip install document-svg
```

Install `document-svg`, import `document_svg`. Ready-made packages cover
Windows, macOS and Linux (Ubuntu, Debian and other glibc systems) on x64 and
ARM64, so you don't need Rust. On Alpine and other musl systems, pip builds
from source, which needs Rust and a C linker. This package gives you a Python
API; for the `docsvg` command, see crates.io.

The package goes into your environment's `site-packages/document_svg`.
`python -m pip show document-svg` shows the installed version and location.

## Save SVG pages to a folder

```python
from document_svg import convert

report = convert("report.pdf", "out/report")
print(report["page_count"], report["warnings"])
```

The output folder must be new or empty. It receives `page-0001.svg`,
`page-0002.svg`, … and a `conversion.json` report. Conversion runs without
holding Python's GIL, so other threads keep working.

Useful options:

- `max_pages` — stop after this many pages.
- `jobs` — convert several pages at once.
- `outline_embedded_pdf_text=True` — for PDFs, draw text as shapes so it looks
  exactly like the original on any computer (the text can no longer be
  selected).
- `embed_drawio_source=True` — for draw.io files, keep the diagram inside each
  SVG so it can later be turned back into an editable diagram.

## Get SVG pages in memory

`preview()` returns every page as SVG text without writing files — handy for
a web API or a notebook.

```python
from document_svg import preview

result = preview("slides.pptx", max_pages=20)
first_page_svg = result["pages"][0]["svg"]

if result["needs_review"]:
    print("Some parts were approximated:", result["warnings"])
```

When you show pages in a web page, show them as images (for example an
`<img>` element) rather than inserting the SVG markup into your HTML.

## Read the result before you share it

Every result has `warnings`: things that were approximated or left out, such
as a substituted font or an unsupported fill. Finishing without an error is not
the same as perfect. When there are warnings, have a person look at the pages.

Text uses the fonts available where the SVG is shown, so it can look slightly
different on another computer.

## Turn SVG pages back into files

```python
from document_svg import reverse

reverse("out/slides", "slides.pptx")   # a folder of pages
reverse("drawing.svg", "drawing.dxf")  # or a single SVG
```

The extension decides the format: PowerPoint, Word, Excel, draw.io, DXF,
G-code, Gerber, HP-GL and more. What comes back is how the pages look;
paragraphs, cells and formulas are not rebuilt. A draw.io diagram converted
with `embed_drawio_source=True` comes back editable.

## Tidy up an SVG

```python
from document_svg import transform

smaller = transform(svg, minify=True, remove_metadata=True)
```

`transform()` can also recolour to one colour, make the SVG scale to its
container, and clean up paths and empty groups. It returns `str` for `str`
input and `bytes` for `bytes` input.

## Which files work?

PDF, Word, Excel and PowerPoint (current and older formats), OpenDocument,
e-mail, e-books, draw.io, Visio, Mermaid, PlantUML, DXF, Gerber, G-code, STL,
STEP, IFC, simulation meshes, CSV, JSON, maps, images, DICOM and more. Some
formats are drawn in full; others show a summary of their contents. Look up
your file type in the [searchable format list](https://ryusui-hiro.github.io/document-svg/formats.html).

## Safety

- Treat uploaded files as untrusted. On a public service, run conversion in a
  separate process with memory and time limits.
- Input size, archive contents and page count are limited by default. Don't
  raise the limits just to push a difficult file through.
- A PDF that needs a password to open is refused.
- Medical images and reports are not anonymized: personal information in the
  file can appear in the output.

More in [Safety and limits](https://ryusui-hiro.github.io/document-svg/safety.html)
and the [security policy](https://github.com/ryusui-hiro/document-svg/blob/main/SECURITY.md).

## Building from source

For contributors, from `bindings/python` (Rust required):

```sh
python -m pip wheel --no-deps --wheel-dir dist .
```

## License

MIT OR Apache-2.0. See the
[repository](https://github.com/ryusui-hiro/document-svg#license) for the
license texts and third-party notices.

