Metadata-Version: 2.5
Name: prince-pdf
Version: 17.0.0.post2
Summary: Prince: convert HTML with CSS to PDF. Bundles the Prince engine - no separate install required.
Project-URL: Homepage, https://www.princexml.com/
Project-URL: Prince Manual, https://www.princexml.com/doc/
Project-URL: Repository, https://github.com/yeslogic/prince-python
Project-URL: Bug Tracker, https://github.com/yeslogic/prince-python/issues
Author: YesLogic Pty Ltd
License-Expression: MIT AND LicenseRef-Prince-License-Agreement
License-File: LICENSE
License-File: LICENSE-Prince.txt
Keywords: css,html,html to pdf,markdown,paged media,pdf,prince,princexml,typesetting
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Printing
Classifier: Topic :: Text Processing :: Markup :: HTML
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# prince-pdf

Python packaging of [Prince](https://www.princexml.com/), the HTML-with-CSS
to PDF engine. The wheel bundles the Prince engine for the current platform:
no separate installation, and neither installing the package nor launching
the engine downloads anything. (Prince will access the network only if a
document being converted references remote resources such as images or
stylesheets.)

```
pip install prince-pdf
```

```python
import prince_pdf

prince_pdf.convert("document.html", "document.pdf")

pdf_bytes = prince_pdf.html_to_pdf("<h1>Hello</h1>")    # in-memory

pdf_bytes = prince_pdf.markdown_to_pdf("# Hello")
```

The package also puts `prince` on `PATH`, so the full
[command-line interface](https://www.princexml.com/doc/command-line/) works
as documented:

```
prince document.html -o document.pdf
```

`python -m prince_pdf` also works anywhere the package is importable, even
when the script directory is not on `PATH`.

## Names

One package, three names: install it as **`prince-pdf`**, import it as
**`prince_pdf`**, run it as **`prince`**. Note that `pip install prince`
installs an unrelated statistics library, not this package.

## Files vs. strings

`convert()` always interprets strings as filesystem paths, never as
document content. To convert an HTML string, use `html_to_pdf()`.

The `*_to_pdf` functions pipe the document through the engine's standard
input, so the engine never sees a filename: relative URLs in the document
are resolved against the current working directory, not against wherever
the content originally came from. If a string derived from
`/tmp/report/index.html` references `images/chart.svg`, pass the original
location as a base URL:

```python
prince_pdf.html_to_pdf(html, args=("--baseurl", "/tmp/report/"))
```

## Using a separately installed Prince

The bundled engine is the default, but the wrapper can drive an existing
Prince installation instead — a licensed system install, or a newer
engine. Set the `PRINCE_PATH` environment variable to the installation's
`prince` executable (the command you would normally run — pointing it at
a directory is rejected with an error), or select one per call:

```python
prince_pdf.convert("doc.html", "doc.pdf", executable="/usr/bin/prince")
```

The per-call `executable` argument overrides `PRINCE_PATH`, which
overrides the bundled engine. External engines run without `--prefix`,
so the installation locates its own style sheets, fonts, and license.
`PRINCE_LICENSE_FILE` is honored either way.

## Python API

The package ships inline type annotations (`py.typed`).

- `prince_pdf.convert(inputs, output=None, args=())` — convert one or more
  files (HTML, XML, SVG; Markdown with Prince 17+; a list is merged into
  one PDF), with the format detected from each file. Extra command-line
  options go in `args` as a sequence of individual argument tokens —
  `args=("--baseurl", "https://x.example/")`, never a shell string like
  `"--baseurl https://x.example/"`. Returns the output path, or the PDF
  as `bytes` when `output` is None.
- `prince_pdf.html_to_pdf(html, output=None, args=())`,
  `prince_pdf.markdown_to_pdf(markdown, ...)`,
  `prince_pdf.xml_to_pdf(xml, ...)` — convert a document given as a string
  or bytes, without temporary files. Markdown input requires Prince 17
  or later.
- Failures raise `PrinceError` carrying `.returncode`, raw `.stderr`, and
  `.messages` — the engine's diagnostics parsed into
  `Message(severity, location, text)` tuples. During successful
  conversions, engine warnings are emitted on the `"prince_pdf"` logger;
  pass `on_message=` to receive every diagnostic yourself instead (an
  exception from the callback aborts the call).
- `prince_pdf.run(*args, **kwargs)` — a thin `subprocess.run()` wrapper
  for raw engine access. It does **not** apply the error handling or
  diagnostic parsing that `convert()` provides: nonzero exits do not
  raise (pass `check=True` for `CalledProcessError`), and output is not
  captured unless requested.
- `prince_pdf.command(*args)` — the argv list that would be run, for use
  with external process tooling (same caveats as `run()`).
- `prince_pdf.executable()` — path of the engine that will be invoked
  (the bundled engine, unless `PRINCE_PATH` selects another).
- `prince_pdf.version()` — the engine's version string.
- `prince_pdf.license()` — the default license-file location inside the
  bundle (prefer `PRINCE_LICENSE_FILE`, which survives reinstalls).

## Licensing

Prince may be used without a purchased license under the conditions in the
included Prince License Agreement (`LICENSE-Prince.txt`); unlicensed output
carries a watermark on the first page. Commercial use requires an
appropriate [license from YesLogic](https://www.princexml.com/purchase/).
Point the engine at your license file with the `PRINCE_LICENSE_FILE`
environment variable (preferred — it survives reinstalls), or install it
at the path returned by `prince_pdf.license()`. The Python wrapper code
itself is MIT-licensed (`LICENSE`).

## Troubleshooting

- **Missing or wrong fonts in minimal containers**: the wheel bundles the
  engine but uses the system's fonts. Install some, e.g.
  `apt-get install fonts-dejavu fontconfig` (Debian/Ubuntu) or
  `apk add fontconfig ttf-dejavu` (Alpine).
- **`libfontconfig.so.1: cannot open shared object file` (Linux x86-64)**:
  install the system fontconfig library, e.g.
  `apt-get install libfontconfig1` — installing fonts as above also
  provides it.
- **Watermark on the first page**: expected without a license — see
  Licensing above.
- **Documents referencing remote resources**: fetching `http(s)` images or
  stylesheets requires network access at conversion time; self-contained
  local files need none.
- **`No matching distribution found for prince-pdf`**: this means pip
  couldn't reach or match, not necessarily that the package doesn't
  exist. In sandboxed environments, check proxy settings
  (`pip config list`, `HTTP_PROXY`/`NO_PROXY`) — the registry may only
  be reachable through the sandbox's egress proxy. It can also mean no
  wheel exists for the platform (see Supported platforms below).
- **Diagnosing failures**: `PrinceError.stderr` carries the engine's
  warnings and errors; add `--verbose` (or `-o` plus `--log=FILE`) for
  more detail.

## Supported platforms

Linux x86-64 and ARM64 (glibc), musl/Alpine ARM64, macOS 10.13+
(universal), Windows x64 and ARM64. On Linux x86-64 the engine
additionally needs the system fontconfig library — in minimal containers,
`apt-get install libfontconfig1` (it usually arrives with fonts anyway).

Python 3.8 or later.

---

Maintainer documentation — how wheels are built, verified, and released —
is in
[RELEASING.md](https://github.com/yeslogic/prince-python/blob/main/RELEASING.md).
A Node.js equivalent of this package is
[available on npm](https://www.npmjs.com/package/prince-pdf) under the
same name.
