pp.server - Produce & Publish Server
Project description
pp.server is a Pyramid 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)
PhantomJS (free, unsupported)
Speedata Publisher (www.speedata.de, open-source, experimental support)
WKHTMLTOPDF (www.wkhtmltopdf.org, open-source, experimental support)
In addition there is experimental support for generating EPUB documents using Calibre (www.calibre.org, open-source).
In addition the Produce & Publish server provides a simple conversion API for converting format A to B (as supported through LibreOffice or OpenOffice). The conversion is build on top of unoconv.
The web service provides both synchronous and asynchronous operations.
Requirements
Python 3.3 or higher, no support for Python 2.x
the external binaries
PrinceXML: prince,
PDFreactor: pdfreactor,
Unoconv: unoconv
Speedata Publisher: sp
Calibre: ebook-convert
WKHTMLTOPDF: wkhtmltopdf
must be in the $PATH. Please refer to the installation documentation of the individual products.
Installation
create an virtualenv environment (Python 2.7 (or Python 3.4)) - either within your current (empty) directory or by letting virtualenv create one for you. (easy_install virtualenv if virtualenv is not available on your system):
virtualenv --no-site-packages .
or:
virtualenv --no-site-packages pp.server
install the Produce & Publish server:
bin/pip install pp.server
create a server.ini configuration file (and change it according to your needs):
[DEFAULT] debug = true [app:main] use = egg:pp.server reload_templates = true debug_authorization = false debug_notfound = false [server:main] use = egg:waitress#main host = 127.0.0.1 port = 6543
start the server (in foreground):
bin/pserve server.ini
or start it in background:
bin/pserve server.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 for PDFreactor
phantomjs for PhantomJS
wkhtmltopdf for WKHTMLToPDF
ebook-convert for Calibre
sp for the Speedata Publisher
API documentation
All API methods are available through a REST api following API URL endpoint:
http://host:port/api/1/<command>
With the default server configuration this translates to:
http://localhost:6543/api/1/pdf or http://localhost:6543/api/1/unoconv
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
with the following parameters:
file - the ZIP archive (multi/part encoding)
converter - a string that determines the the PDF converter to be used (either princexml, pdfreactor, phantomjs or calibre for generating EPUB content)
async - asynchronous (“1”) or synchronous conversion (“0”, default)
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)
Unoconv conversion API
The unoconv web service wraps the OpenOffice/LibreOffice server mode in order to perform document conversion (mainly used in the Produce & Publish world for convertering DOC(X) documents to HTML/XML).
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
with the following parameters:
file - the source files (multi/part encoding)
async - asynchronous (“1”) or synchronous conversion (“0”, default)
cmd_options - an optional string of command line parameters added as given to the unoconv calls
Returns:
The API returns its result as JSON structure with the following key-value pairs:
status - either OK or ERROR
data - the converted output files as ZIP archive (e.g. a DOCX file containing images will be converted to a HTML file plus the list of extract image files)
output - the conversion transcript (output of the converter run)
Asynchronous operations
If you set async to ‘1’ in the API calls above then both calls will return a JSON datastructure like
{‘job_id’: <some id>}
The job_id can be used to poll the Produce & Publish Server in order to retrieve the conversion result asynchronously.
The poll API is provided through the URL
http://host:port/api/1/poll/<job_id>
If the conversion is still pending the API will return a JSON document
{‘done’: False}
If the conversion has finished then a PDF/Unoconv specific return JSON document will be return (same format as for the synchronous API calls). In addition the key-value pair {‘done’: True} will be included with the JSOn reply.
Introspection API methods
Produce & Publish server version:
returns:
{“version”: “0.3.2”, “module”: “pp.server”}
Installed/available converters:
returns:
{“unoconv”: true, “pdfreactor”: true, “phantomjs”: false, “calibre”: true, “princexml”: true}
Versions of installed converter:
returns:
{‘princexml’: ‘Version x.y’, ‘pdfreactor: ‘Version a.b.c’, …}
Other API methods
Cleanup of the queue directory (removes conversion data older than one day)
returns:
{“directories_removed”: 22}
Advanced installation issues
Installation of PDFreactor using zc.buildout
Installation of PrinceXML using zc.buildout
Production setup
pserve and celeryd can be started automatically and controlled using Circus. Look into the following buildout configuration
Source code
Bug tracker
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
0.6.1 (2015/02/02)
add /api/converter-versions to webservice API
0.6.0 (2015/01/26)
dropped Python 2.X support, Python 3.3 or higher is now a mandatory requirement
0.5.5 (2015/01/23)
UTF8 handling fix
0.5.3 (2014/11/23)
support for WKHTMLTOPDF
0.5.2 (2014/11/19)
support for Speedata Publisher
0.5.1 (2014/10/12)
improved error handling
0.5.0 (2014/10/12)
official Python 3.3/3.4 support
0.4.7 (25.09.2014)
fixed documentation bug
0.4.6 (22.08.2014)
removed PDFreactor –addlog option
0.4.5 (22.08.2014)
added supplementary commandline options to pdfreactor commandline call
0.4.4 (24.01.2014)
minor typos fixed
0.4.3 (20.01.2014)
implemented automatic queue cleanup after one day
0.4.2 (18.01.2014)
URL fix in index.pt related to virtual hosting
0.4.1 (13.01.2014)
show Python version and converters on index.pt
authorization support added
0.4.0 (17.10.2013)
Python 3.3 support
Pyramid 1.5 support
0.3.5 (05.10.2013)
added ‘cmd_options’ to pdf and unoconv API methods for specifying arbitary command line parameters for the external converters
0.3.4 (05.10.2013)
added ‘cleanup’ API
0.3.3 (05.10.2013)
added ‘version’ and ‘converter’ API methods
0.3.2 (04.10.2013)
added support EPUB conversion using Calibre
0.3.1 (03.10.2013)
updated documentation
0.3.0 (14.07.2013)
unoconv conversion now returns a ZIP archive (e.g. a HTML file + extracted images)
0.2.7 (06.07.2013)
added support for Phantom.js converter
0.2.5 (05.07.2013)
better detecting of prince and pdfreactor binaries
0.2.2 (05.07.2013)
updated the documentation
minor cleanup
0.2.1 (04.07.2013)
re-added poll API
0.2.0 (03.07.2013)
converted XML-RPC api to REST api
0.1.9 (01.07.2013)
monkeypatch pyramid_xmlrpc.parse_xmlrpc_request in order to by-pass its stupid DOS request body check
0.1.7 (29.06.2013)
more tests
fixes
updated documentation
0.1.5 (27.06.2013)
test for synchronous operations
fixes
0.1.0 (24.06.2013)
initial release
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
