Metadata-Version: 2.4
Name: zconvert
Version: 1.2.0
Summary: ZConvert client — HTML decks to native PowerPoint, Markdown to PDF/DOCX
License-Expression: MIT
Project-URL: Homepage, https://github.com/YatchiYa/html-to-pptx
Project-URL: Repository, https://github.com/YatchiYa/html-to-pptx
Project-URL: Issues, https://github.com/YatchiYa/html-to-pptx/issues
Keywords: pptx,powerpoint,html,markdown,pdf,docx,converter
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Office Suites
Classifier: Topic :: Text Processing :: Markup :: HTML
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# zconvert

Python client for **ZConvert** — HTML decks to native, editable PowerPoint;
Markdown to PDF and Word.

The client is tiny (one dependency, `httpx`) and talks to a ZConvert server,
which does the rendering. Server, deck-authoring rules and the Node/Rust SDKs:
<https://github.com/YatchiYa/html-to-pptx>.

```bash
pip install zconvert
```

## Use

```python
from zconvert import ZConvert

z = ZConvert("http://localhost:8000")     # or set ZCONVERT_URL

# The source can be a path, a string of content, or bytes.
z.html_to_pptx("deck.html", out="deck.pptx")
z.html_to_pptx(html_string, filename="deck.html", out="deck.pptx")

z.md_to_pdf("# Hello\n\nWorld", out="hello.pdf")
z.md_to_docx("report.md", title="Q4 review", out="report.docx")
```

`out` is optional — every call returns the bytes:

```python
pptx = z.html_to_pptx("deck.html")
```

### Start from a skeleton

`deck.html` documents the HTML deck rules in its own header comment;
`document.md` shows every supported Markdown feature.

```python
z.save_example("deck.html")          # writes ./deck.html
z.save_example("document.md", "docs/document.md")
z.examples()                         # [{name, description, convert_to}, …]
```

### Parameters

Only what you set is sent, so the server's defaults stay authoritative.

```python
z.html_to_pptx(
    "deck.html",
    mode="image",            # "native" (default, editable) | "image" (pixel-exact)
    embed_fonts=False,       # default True
    real_background=False,   # default True
    font_body="Inter",
    font_heading="Poppins",
    timeout_ms=60_000,       # per-slide render budget
)

z.md_to_pdf("report.md", title="Q4 review")
```

### Styling the document

```python
z.md_to_pdf("report.md", theme="violet")        # slate (default), graphite, blue,
                                                # violet, emerald, crimson, amber, teal
z.md_to_docx("report.md", accent="#0d9488")     # any hex colour
z.md_to_pdf("report.md", captions=False)        # drop the "Figure N" numbering
```

The theme recolours headings, links, list markers, table headers and the chart
palette. PDF and DOCX read the same one, so the two stay in step.

`convert()` is the general form when you want to pass `to` yourself:

```python
z.convert("report.md", to="docx", out="report.docx")
```

HTML converts to `pptx` only; Markdown converts to `pdf` or `docx`. An
impossible pair raises `ValueError` **before** any request is made.

### Async

```python
from zconvert import AsyncZConvert

z = AsyncZConvert("http://localhost:8000")
pdf = await z.md_to_pdf("# Hello", filename="hello.md")
```

### Errors

```python
from zconvert import ZConvertError

try:
    z.html_to_pptx("deck.html")
except ZConvertError as e:
    print(e.status, e.detail)     # 422 "no slides found in input"
```

### How a source is interpreted

| You pass | Treated as |
|---|---|
| `Path("deck.html")` | a file, always |
| `"deck.html"` (exists on disk) | a file |
| `"# Title\n\nBody"` (has a newline) | content |
| `"<section>x</section>"` (no such file) | content |
| `b"..."` | content |

Pass `filename=` with inline content: the extension picks the pipeline and the
stem names the output.

## Discovery

```python
z.health()      # {"status": "ok", "version": "1.0.0"}
z.manifest()    # conversions, every parameter, defaults, limits
```

## Test

```bash
pytest      # stubbed transport, no server needed
```
