pp.server 0.4.3

pp.server - Produce & Publish Server

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)

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 2.7 (tested)

or Python 3.3 (experimental)

the external binaries prince, pdfreactor and/or unoconv
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.3)) - 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):

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

ebook-convert for Calibre

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.

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.

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.

Other API methods

Authorization support

The pp.server implementation provides a simple and optional authorization
mechanism by accepting a pp-token header from the client. In order to
enable the authorization support on the server side you need to configure the
authenticator method and the authorization token in your .ini file:

The token_auth string refers to a method in pp.server.authorization
which is a simple authorization method (for the beta phase) supporting only one
token for now. The token is configured through the pp.authentication_token
value.

Any client sending a HTTP request to the pp.server server instance is required
to send a HTTP header for authorization (if enabled on the server):