pp.server - Produce & Publish Server
====================================
.. note::
This new version 3 of the Produce & Publish server is a complete rewrite
with an incompatible REST API. Version 3 also requires version 3
of the `pp.client-python` bindings.
``pp.server`` is a FastAPI based server implementation and implements the
server side functionality of the Produce & Publish platform. It is known as
the ``Produce & Publish Server``.
The Produce & Publish Server provided web service APIs for converting
HTML/XML + assets to PDF using one of the following external PDF converters:
- PrinceXML (www.princexml.com, commercial)
- PDFreactor (www.realobjects.com, commercial)
- Speedata Publisher (www.speedata.de, open-source, experimental support)
- WKHTMLTOPDF (www.wkhtmltopdf.org, open-source, experimental support)
- Vivliostyle Formatter (www.vivliostyle.com, commercial, experimental support)
- VersaType Formatter (www.trim-marks.com, commercial, experimental support)
- Antennahouse 7 (www.antennahouse.com, commercial)
- Weasyprint (free, unsupported)
- Typeset.sh (www.typeset.sh, commercial)
- PagedJS (www.pagedjs.org, free)
In addition there is experimental support for generating EPUB documents
using ``Calibre`` (www.calibre.org, open-source).
The web service provides only synchronous operation.
Requirements
------------
- Python 3.12 or higher, no support for Python 2.x
- the external binaries
- PrinceXML: ``prince``,
- PDFreactor: ``pdfreactor.py``,
- Speedata Publisher: ``sp``
- Calibre: ``ebook-convert``
- WKHTMLTOPDF: ``wkhtmltopdf``
- Vivliostyle: ``vivliostyle-formatter``
- VersaType : ``versatype-converter``
- Weasyprint: ``weasyprint``
- Antennahouse: ``run.sh``
- Typeset.sh: ``typeset.sh.phar``
- PageJS: ``pagedjs-cli``
must be in the $PATH. Please refer to the installation documentation
of the individual products.
Installation
------------
This project uses `uv` as package and virtualenv manager.
- create a Python 3 virtual environment using::
python3 -m venv .venv
- install dependencies using ``uv``::
.venv/bin/uv pip install -e .
- run the Produce & Publish server using the ``pp-server`` script::
.venv/bin/pp-server --host 0.0.0.0 --port 8000
The ``pp-server`` script provides options for setting the host and port, and for enabling auto-reloading of the server on code changes.
- or under control of `gunicorn`::
.venv/bin/gunicorn pp.server.server:app -w 2 -k uvicorn.workers.UvicornWorker
- For running the Produce & Publisher server under control of the process manager
`circus`, generate the `circusd.ini` file using::
.venv/bin/pp-server-templates
- and start it in background::
.venv/bin/circusd circusd.ini --daemon
Converter requirements
----------------------
For the PDF conversion the related converter binaries or scripts
must be included in the ``$PATH`` of your server.
- ``prince`` for PrinceXML
- ``pdfreactor-legacy`` for PDFreactor <= 11
- ``pdfreactor`` for PDFreactor 12 or highter
- ``wkhtmltopdf`` for WKHTMLToPDF
- ``ebook-convert`` for Calibre
- ``sp`` for the Speedata Publisher
- ``vivliostyle`` for the Vivliostyle formatter
- ``versatype`` for the Versatype converter
- ``weasyprint`` for Weasyprint
- ``antennahouse`` for the Antennahouse
- ``pagedjs`` for the PagedJS
- ``typesetsh`` for the Typeset.sh
API documentation
-----------------
All API methods are available through a REST api
following API URL endpoint::
http://host:port/<command>
With the default server configuration this translates to::
http://localhost:8000/convert
REST API Introspection
----------------------
`pp.server` is implemented based on the FastAPI framework for Python.
You can access the REST API documentation directly through
http://localhost:8000/docs
Environment variables
+++++++++++++++++++++
`pp.server` uses the `var` folder of the installation directory by default as
temporary folder for conversion data. Set the environment variable `PP_SPOOL_DIRECTORY`
if you need different spool directory instead.
If you run PDFreactor 10 or higher under Docker then you must set the environment
variable `PP_PDFREACTOR_DOCKER=1` in order to generated a proper `file:///docs/...`
URI for `pdfreactor.py`.
PDF conversion API
++++++++++++++++++
Remember that all converters use HTML or XML as input for the conversion. All
input data (HTML/XML, images, stylesheets, fonts etc.) must be stored in ZIP
archive. The filename of the content **must** be named ``index.html``.
You have to ``POST`` the data to the
http://host:port/convert
with the following parameters:
- ``data`` - the ZIP archive (as base64 encoded string)
- ``converter`` - a string that determines the the PDF
converter to be used (either ``princexml``, ``pdfreactor``, ``phantomjs``, ``vivliostyle``, ``versatype``,
or ``calibre`` for generating EPUB content)
- ``cmd_options`` - an optional string of command line parameters added
as given to the calls of the externals converters
Returns:
The API returns its result as JSON structure with the following key-value
pairs:
- ``status`` - either ``OK`` or ``ERROR``
- ``data``- the generated PDF file encoded as base64 encoded byte string
- ``output`` - the conversion transcript (output of the converter run)
Introspection API methods
+++++++++++++++++++++++++
Produce & Publish server version:
http://host:port/version
returns:
{"version": "3.0.0", "module": "pp.server"}
Installed/available converters:
http://host:port/converters
returns:
{"pdfreactor": true, "phantomjs": false, "calibre": true, "prince": true}
Versions of installed converter:
http://host:port/converter-versions
returns:
{'prince': 'Version x.y', 'pdfreactor: 'Version a.b.c', ...}
Other API methods
+++++++++++++++++
Cleanup of the queue directory (removes conversion data older than one day)
http://host:port/cleanup
returns:
{"directories_removed": 22}
Source code
-----------
https://github.com/zopyx/pp.server
Bug tracker
-----------
https://github.com/zopyx/pp.server/issues
Support
-------
Support for Produce & Publish Server is currently only available on a project
basis.
License
-------
``pp.server`` is published under the GNU Public License V2 (GPL 2).
Contact
-------
| ZOPYX
| Hundskapfklinge 33
| D-72074 Tuebingen, Germany
| info@zopyx.com
| www.zopyx.com
| www.produce-and-publish.info
Raw data
{
"_id": null,
"home_page": null,
"name": "pp.server",
"maintainer": null,
"docs_url": "https://pythonhosted.org/pp.server/",
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "web, fastapi, pdf, unoconv, conversion, princexml, pdfreactor",
"author": null,
"author_email": "Andreas Jung <info@zopyx.com>",
"download_url": "https://files.pythonhosted.org/packages/92/88/f38f5452e2e1da2f93ea23b2148cac421fdbac951962716349776466232b/pp_server-3.5.7.tar.gz",
"platform": null,
"description": "pp.server - Produce & Publish Server\n====================================\n\n\n.. note:: \n\n This new version 3 of the Produce & Publish server is a complete rewrite\n with an incompatible REST API. Version 3 also requires version 3\n of the `pp.client-python` bindings.\n\n``pp.server`` is a FastAPI based server implementation and implements the\nserver side functionality of the Produce & Publish platform. It is known as\nthe ``Produce & Publish Server``.\n\nThe Produce & Publish Server provided web service APIs for converting\nHTML/XML + assets to PDF using one of the following external PDF converters:\n\n- PrinceXML (www.princexml.com, commercial)\n- PDFreactor (www.realobjects.com, commercial)\n- Speedata Publisher (www.speedata.de, open-source, experimental support)\n- WKHTMLTOPDF (www.wkhtmltopdf.org, open-source, experimental support)\n- Vivliostyle Formatter (www.vivliostyle.com, commercial, experimental support)\n- VersaType Formatter (www.trim-marks.com, commercial, experimental support)\n- Antennahouse 7 (www.antennahouse.com, commercial)\n- Weasyprint (free, unsupported)\n- Typeset.sh (www.typeset.sh, commercial)\n- PagedJS (www.pagedjs.org, free)\n\nIn addition there is experimental support for generating EPUB documents\nusing ``Calibre`` (www.calibre.org, open-source).\n\nThe web service provides only synchronous operation.\n\nRequirements\n------------\n\n- Python 3.12 or higher, no support for Python 2.x\n\n- the external binaries \n\n - PrinceXML: ``prince``, \n - PDFreactor: ``pdfreactor.py``, \n - Speedata Publisher: ``sp``\n - Calibre: ``ebook-convert``\n - WKHTMLTOPDF: ``wkhtmltopdf`` \n - Vivliostyle: ``vivliostyle-formatter`` \n - VersaType : ``versatype-converter`` \n - Weasyprint: ``weasyprint`` \n - Antennahouse: ``run.sh`` \n - Typeset.sh: ``typeset.sh.phar`` \n - PageJS: ``pagedjs-cli`` \n\n must be in the $PATH. Please refer to the installation documentation\n of the individual products.\n\nInstallation\n------------\n\nThis project uses `uv` as package and virtualenv manager.\n\n- create a Python 3 virtual environment using::\n\n python3 -m venv .venv\n\n- install dependencies using ``uv``::\n\n .venv/bin/uv pip install -e .\n\n- run the Produce & Publish server using the ``pp-server`` script::\n\n .venv/bin/pp-server --host 0.0.0.0 --port 8000\n\n The ``pp-server`` script provides options for setting the host and port, and for enabling auto-reloading of the server on code changes.\n\n- or under control of `gunicorn`::\n\n .venv/bin/gunicorn pp.server.server:app -w 2 -k uvicorn.workers.UvicornWorker\n\n\n- For running the Produce & Publisher server under control of the process manager\n `circus`, generate the `circusd.ini` file using::\n\n .venv/bin/pp-server-templates\n\n- and start it in background::\n\n .venv/bin/circusd circusd.ini --daemon\n\nConverter requirements\n----------------------\n\nFor the PDF conversion the related converter binaries or scripts\nmust be included in the ``$PATH`` of your server.\n\n- ``prince`` for PrinceXML\n\n- ``pdfreactor-legacy`` for PDFreactor <= 11 \n\n- ``pdfreactor`` for PDFreactor 12 or highter\n\n- ``wkhtmltopdf`` for WKHTMLToPDF\n\n- ``ebook-convert`` for Calibre\n\n- ``sp`` for the Speedata Publisher\n\n- ``vivliostyle`` for the Vivliostyle formatter\n\n- ``versatype`` for the Versatype converter\n\n- ``weasyprint`` for Weasyprint\n\n- ``antennahouse`` for the Antennahouse\n\n- ``pagedjs`` for the PagedJS\n\n- ``typesetsh`` for the Typeset.sh\n\n\n\nAPI documentation\n-----------------\n\nAll API methods are available through a REST api\nfollowing API URL endpoint::\n\n http://host:port/<command>\n\nWith the default server configuration this translates to::\n\n http://localhost:8000/convert\n\nREST API Introspection\n----------------------\n\n`pp.server` is implemented based on the FastAPI framework for Python.\nYou can access the REST API documentation directly through\n \n http://localhost:8000/docs\n\nEnvironment variables\n+++++++++++++++++++++\n\n`pp.server` uses the `var` folder of the installation directory by default as\ntemporary folder for conversion data. Set the environment variable `PP_SPOOL_DIRECTORY` \nif you need different spool directory instead. \n\nIf you run PDFreactor 10 or higher under Docker then you must set the environment\nvariable `PP_PDFREACTOR_DOCKER=1` in order to generated a proper `file:///docs/...`\nURI for `pdfreactor.py`.\n\n\nPDF conversion API\n++++++++++++++++++\n\nRemember that all converters use HTML or XML as input for the conversion. All\ninput data (HTML/XML, images, stylesheets, fonts etc.) must be stored in ZIP\narchive. The filename of the content **must** be named ``index.html``.\n\nYou have to ``POST`` the data to the \n\n http://host:port/convert\n\nwith the following parameters:\n\n\n- ``data`` - the ZIP archive (as base64 encoded string)\n\n- ``converter`` - a string that determines the the PDF\n converter to be used (either ``princexml``, ``pdfreactor``, ``phantomjs``, ``vivliostyle``, ``versatype``, \n or ``calibre`` for generating EPUB content)\n\n- ``cmd_options`` - an optional string of command line parameters added \n as given to the calls of the externals converters\n\n\nReturns:\n\nThe API returns its result as JSON structure with the following key-value\npairs:\n\n- ``status`` - either ``OK`` or ``ERROR``\n\n- ``data``- the generated PDF file encoded as base64 encoded byte string\n\n- ``output`` - the conversion transcript (output of the converter run)\n\n \nIntrospection API methods\n+++++++++++++++++++++++++\n\nProduce & Publish server version:\n\n http://host:port/version\n\nreturns:\n\n {\"version\": \"3.0.0\", \"module\": \"pp.server\"}\n \nInstalled/available converters:\n\n http://host:port/converters\n\nreturns:\n\n {\"pdfreactor\": true, \"phantomjs\": false, \"calibre\": true, \"prince\": true}\n\n\nVersions of installed converter:\n\n http://host:port/converter-versions\n\nreturns:\n\n {'prince': 'Version x.y', 'pdfreactor: 'Version a.b.c', ...}\n\n\nOther API methods\n+++++++++++++++++\n\nCleanup of the queue directory (removes conversion data older than one day)\n\n http://host:port/cleanup\n\nreturns:\n\n {\"directories_removed\": 22}\n\n\nSource code\n-----------\n\nhttps://github.com/zopyx/pp.server\n\nBug tracker\n-----------\n\nhttps://github.com/zopyx/pp.server/issues\n\nSupport\n-------\n\nSupport for Produce & Publish Server is currently only available on a project\nbasis.\n\nLicense\n-------\n``pp.server`` is published under the GNU Public License V2 (GPL 2).\n\nContact\n-------\n\n| ZOPYX \n| Hundskapfklinge 33\n| D-72074 Tuebingen, Germany\n| info@zopyx.com\n| www.zopyx.com\n| www.produce-and-publish.info\n",
"bugtrack_url": null,
"license": null,
"summary": "pp.server - Produce & Publish Server",
"version": "3.5.7",
"project_urls": {
"Homepage": "http://pypi.python.org/pypi/pp.server"
},
"split_keywords": [
"web",
" fastapi",
" pdf",
" unoconv",
" conversion",
" princexml",
" pdfreactor"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e0b5b7275fea828e42c7365cb8769ab4716829d7a26992adf33a345e1c12092e",
"md5": "c377d1959c66000dbb5a20769aad5142",
"sha256": "82c611e38aa8b8be1e0a1e5422097e066eeef2a28adf63cf3bba56aeb07bab92"
},
"downloads": -1,
"filename": "pp_server-3.5.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c377d1959c66000dbb5a20769aad5142",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 112590,
"upload_time": "2025-10-06T13:24:23",
"upload_time_iso_8601": "2025-10-06T13:24:23.059911Z",
"url": "https://files.pythonhosted.org/packages/e0/b5/b7275fea828e42c7365cb8769ab4716829d7a26992adf33a345e1c12092e/pp_server-3.5.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9288f38f5452e2e1da2f93ea23b2148cac421fdbac951962716349776466232b",
"md5": "da6e707428be8a2f96b4d2f2c11b8b5b",
"sha256": "da89f6cdb90ec7357d0a700f7d025b3259d3ef84c0638d432beb08ebe143f114"
},
"downloads": -1,
"filename": "pp_server-3.5.7.tar.gz",
"has_sig": false,
"md5_digest": "da6e707428be8a2f96b4d2f2c11b8b5b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 115373,
"upload_time": "2025-10-06T13:24:24",
"upload_time_iso_8601": "2025-10-06T13:24:24.816754Z",
"url": "https://files.pythonhosted.org/packages/92/88/f38f5452e2e1da2f93ea23b2148cac421fdbac951962716349776466232b/pp_server-3.5.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 13:24:24",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pp.server"
}
JSON