Package apexofficeprint

This Python package provides a programmatic interface with an APEX Office Print server.

Examples

The examples below call this package aop.

import apexofficeprint as aop

Templates

Templates are represented by Resource. The simplest way to obtain a Resource is to load from a local path.

template = aop.Resource.from_local_file("./path/to/template.docx")

Render elements

Most render elements encapsulate the data for a single tag. An elements.Object is an element which represents a collection of elements.

Combining a simple line chart and some text tags:

line = aop.elements.LineChart(
    "linechart",
    aop.elements.LineSeries([1, 2, 3, 4], [1, 2, 3, 4], color="green"),
    aop.elements.XYSeries([1, 2, 3, 4], ["a", "b", "c", "d"])
)

text_tag = aop.elements.Property("tag-name", "Hello, world!")
# or multiple at once using Object.from_mapping
# and supplying the dictionary representation directly
text_tags = aop.elements.Object.from_mapping({
    "another-tag": "Foo",
    "one-more-tag": "Bar"
})

combined_data = aop.elements.Object()
combined_data.add(line)
combined_data.add(text_tag)
combined_data.add_all(text_tags)

The server

An AOP server is configured as a config.Server. It takes an url and an optional config.ServerConfig which allows for various server configuration options. If you're using APEX Office Print Cloud edition, you will need to use this to declare your API key.

server = aop.config.Server(
    "http://server.url.com/",
    aop.config.ServerConfig(api_key = "YOUR_API_KEY")
)

PrintJob combines template, data, server and an optional output configuration (config.OutputConfig) and can execute itself on the AOP server. An example using the variables declared throughout the previous examples.

printjob = aop.PrintJob(template, combined_data, server)
printjob.execute()

A print job can be executed asynchronously as well.

import asyncio
coroutine = printjob.execute_async()
# simply await your result when you need it
result = await coroutine

Full JSON available

If you already have the JSON to be sent to the server (not just the data, but the entire JSON body including your API key and template), this package will wrap the request to the server for you (requests are made using requests).

json_data = open("./path/to/data.json", "r").read()
aop.PrintJob.execute_full_json(
        json_data, server
    ).to_file("./test/from_full_json_output")

Server errors

In case the AOP server returns an error, PrintJob will throw one as well. You can catch it and get either its user-readable message or an encoded stack trace that can be passed to AOP support.

try:
    # execute some previously constructed printjob
    printjob.execute()
except aop.exceptions.AOPError as err:
    print("AOP error! " + err.user_message)
    print(err.encoded_message)
    ...

Sub-modules

apexofficeprint.config

Module for output configurations …

apexofficeprint.elements

Elements are used to replace the various tags in a template with actual data.

apexofficeprint.exceptions

Custom exceptions for apexofficeprint.

apexofficeprint.printjob

Module containing the PrintJob class, which is also exposed at package level.

apexofficeprint.resource

Module containing the Resource class and its subclasses, which is also exposed at package level …

apexofficeprint.response

Module containing the Response class, which is also exposed at package level.

Classes

class PrintJob (template: Resource, data: Union[Element, Mapping[str, Element]], server: Server, output_config: OutputConfig = None)

A print job for a AOP server.

This class contains all configuration options, resources, render elements … and the PrintJob.execute() method to combine all these and send a request to the AOP server.

Args

template : Resource
PrintJob.template.
data : Union[Element, Mapping[str, Element]]
PrintJob.data.
server : Server
PrintJob.server.
output_config : OutputConfig, optional
Printjob.output_config. Defaults to OutputConfig().

Static methods

def execute_full_json(json_data: str, server: Server) ‑> Response
async def execute_full_json_async(json_data: str, server: Server) ‑> Response

Instance variables

var as_dict : dict

dict representation of this print job.

This representation is isomorphic to the json representation (PrintJob.json).

var data

This is either: - An Element (e.g. an Object) - A mapping, containing file names as keys and an Element as data. Multiple files will be produced from the different datas, the result is a zip file containing them. In the first case, no output file name is specified and the server will name it "file0".

var json : str

json equivalent of the dict representation of this print job.

var output_config

Output configuration to be used for this print job.

var server

Server to be used for this print job.

var subtemplates

Subtemplates for this print job, accessible (in docx) through {?include subtemplate_dict_key}

var template

Template to use for this print job.

Methods

def execute(self) ‑> Response

Execute this print job.

async def execute_async(self) ‑> Response

Async version of PrintJob.execute()

class Resource (data=None, filetype: str = None)

The abstract base class for the resources.

Ancestors

  • abc.ABC

Subclasses

Static methods

def from_base64(base64string: str, filetype: str) ‑> Base64Resource

Create a Resource from a base64 string and a file type (extension).

Args

base64string : str
base64 encoded string
filetype : str
file type (extension)

Returns

Base64Resource
the created Resource
def from_html(htmlstring: str, landscape: bool = False) ‑> HTMLResource

Create an HTMLResource with html data in plain text.

Landscape is not supported for prepend/append sources, only for template resources.

Args

htmlstring : str
html content
landscape : bool, optional
whether to use the landscape option. Defaults to False.

Returns

HTMLResource
the created Resource
def from_local_file(local_path: str) ‑> RawResource

Create a RawResource with the contents of a local file.

Throws IOError if it can't read the file. The filetype is determined by the extension of the file.

Args

local_path : str
path to local file

Returns

RawResource
the created Resource
def from_raw(raw_data, filetype: str) ‑> RawResource

Create a RawResource from raw file data and a file type (extension).

Args

raw_data
raw data as a bytes-like object
filetype : str
file type (extension)

Returns

RawResource
the created Resource
def from_server_path(path: str) ‑> ServerPathResource

Create a ServerPathResource targeting a file on the server.

The filetype is determined by the extension of the file.

Args

path : str
location of target file on the server

Returns

ServerPathResource
the created Resource
def from_url(url: str, filetype: str) ‑> URLResource

Create an AOPResource targeting the file at url with given filetype (extension).

Args

url : str
file url
filetype : str
file type (extension)

Returns

URLResource
the created Resource
def is_supported_resource_type(type_: str) ‑> bool

Check if the given resource type is a supported resource type.

Args

type_ : str
resource type (extension)

Returns

bool
whether the given resource type is a supported resource type

Instance variables

var data

The data contained in this AOPResource.

var filetype : str

Resource type as an extension (e.g. "docx").

Raises

TypeError
the given type is not a supported resource type.
var mimetype : str

Resource type as a mime type

var secondary_file_dict : dict

This Resource object as a dict object for use as a secondary file (prepend, append, insert, as subtemplate).

This dict and the "concat file" json representation (Resource.secondary_file_json) are isomorphic.

var secondary_file_json : str

The json representation for use as secondary file.

var template_dict : dict

This Resource object as a dict object for use as a template.

This dict and the template json representation (Resource.template_json) are isomorphic.

var template_json : str

Get the json representation when used as a template.

class Response (response: requests.models.Response)

The Response class serves as a container for and interface with the AOP server's response to a printjob request.

The AOP server can also throw an error, in which case you will be dealing with an apexofficeprint.exceptions.AOPError instead of this class.

You should never need to construct a Response manually.

Args

response : requests.Response
Response object from the requests package

Instance variables

var binary : bytes

Binary representation of the output file.

Response.to_file can be used to output to a file, alternatively, use this property to do something else with the binary data.

Returns

bytes
response file as binary
var filetype : str

File type (extension) of this response. E.g. "docx".

var mimetype : str

Mime type of this response.

Methods

def to_file(self, path: str)

Write the response to a file at the given path without extension.

If the given file path does not contain an extension, the correct path is automatically added from the response data. That is how this method is intended to be used. You should only specify the extension in the path if you have some reason to specify the extension manually.

Args

path : str
path without extension