PythonReports Printout

Version: 0.7.0
Date: 1-apr-2017

Introduction

PythonReports Printout files are "built" reports, ready to be rendered with a frontend driver. Printouts are stored in XML files with extension .PRP.

This document describes printout structures.

The overall structure of printouts is very simple: printout contains one or more page elements, and each page contains outline, text, line, rectangle, image, and barcode elements, each having it's final dimensions and placement.

printout element also contains font definitions and may contain named data elements providing bitmaps for repeated images.

Types of element attributes

This section explains special attribute types used in element descriptions.

Booleans

Values true, yes, and 1 stand for boolean True, values false, no, and 0 stand for boolean False. Recommended form is true and false.

Colors

Color values may be specified in one of the following forms:

  • 6-digit hexadecimal number prefixed by a hash mark (HTML format),
  • color name from the following dictionary (case insensitive),
  • three integer values: red, green, blue (0..255),
  • three float values: red, green, blue (0..1),
  • single integer value, where
    • the red component is in bits 16-23,
    • the green component is in bits 8-15,
    • the blue component is in bits 0-7.

Recommended form is the first one.

Standard color names:

Name Value Name Value
BLACK #000000 YELLOW #FFFF00
SILVER #C0C0C0 NAVY #000080
GRAY #808080 BLUE #0000FF
WHITE #FFFFFF TEAL #008080
MAROON #800000 AQUA #00FFFF
RED #FF0000 CYAN #00FFFF
PURPLE #800080 DARKGRAY #404040
FUCHSIA #FF00FF LIGHTGRAY #C0C0C0
GREEN #008000 MAGENTA #FF00FF
LIME #00FF00 ORANGE #FFC800
OLIVE #808000 PINK #FFAFAF

Dimensions

All report dimensions (page and field sizes, margins, etc.) are expressed as integer or floating point numbers with optional suffix:

  • mm - millimeters,
  • cm - centimeters,
  • in - inches,
  • pt - points (1/72 inch).

If suffix is omitted, dimension is in points.

It is recommended to always use integral points for all dimensions to avoid rounding errors.

The origin of the coordinate system (0,0) is always in the left upper corner of a container (page or section).

Timestamps

Dates and times are recorded in ISO format, e.g. 2006-06-14T14:20:47.

Printout elements

This chapter contains informal descriptions of the printout elements.

In element attribute tables, the second column (Req) shows whether the attribute is required: M for mandatory attributes, O for optional ones.

All elements and attributes not mentioned here are ignored by PythonReports. Element contents (text) are ignored except for data elements.

printout

The root element of the printout tree. Contains elements of types font, data, and page.

Attributes:

Name Req Type Description
name O string Report name. [1]
description O string Description of the report. [1]
version O string Report version. [1]
author O string Author name. [1]
basedir O string Base directory for image file paths. Default: directory containing printout file.
built O timestamp Date and time of report build.
[1](1, 2, 3, 4) copied from report template.

data

Contains arbitrary data for use in text, image, and barcode elements.

This is the only element in PythonReports templates that has significant body text; for all other elements body text is ignored.

Attributes:

Name Req Type Description
name [2] string Data reference needed to use the data in elements other than immediate parent element.
compress O string zlib or bz2.
encoding O string base64, uu or qp.
[2]Ignored when immediate parent element is text, image, or barcode; required otherwise.

font

Font definition for use in text blocks.

Attributes:

Name Req Type Description
name M string Local name of font definition. Used as font reference in text blocks.
typeface M string Typeface name.
size M integer Font size in points.
bold O boolean True for bold fonts.
italic O boolean True for italic fonts.
underline O boolean True for underlined text.

page

Single output page. Child elements are outline, text, line, rectangle, image, and barcode.

Attributes:

Name Req Type Description
width M dimension Page width (including margins).
height M dimension Page height (including margins).
leftmargin M dimension Left page margin.
rightmargin M dimension Right page margin.
topmargin M dimension Top page margin.
bottommargin M dimension Bottom page margin.

box

Required child for all elements placed in pages, i.e. text, line, rectangle, image, and barcode.

Attributes:

Name Req Type Description
x M dimension Horizontal position.
y M dimension Vertical position.
width M dimension Element width.
height M dimension Element height.

text

A textual block. The text to print is contained in child data element.

Attributes:

Name Req Type Description
font M string Name of the font definition.
align O string Text alignment: left, center, right, or justified. Default: left.
color M color Text color.

line

Draw a line.

Attributes:

Name Req Type Description
pen M dimension or string Line style: width of the line or one of dot, dash, dashdot.
color M color Line color.
backslant O boolean When both box dimensions are non-zero, draw the line from upper left corner to lower right one - \ instead of /.

rectangle

Draw a rectangle.

Attributes:

Name Req Type Description
pen M dimension or string Outline style: width of the line or one of dot, dash, dashdot. Use 0 to disable outline.
pencolor M color Outline color.
color O color Fill color. If omitted, the rectangle is transparent.
radius O dimension Corner radius for rounded rectangles. Default: 0

image

Place bitmap image. The bitmap may be loaded from a file or from a data element (either put in the image element or referred by the data attribute.)

Attributes:

Name Req Type Description
type M string Image type, e.g. jpeg or png.
file O string Image file path. If specified, the data is ignored unless the file cannot be loaded.
data O string Name of a data section defined as a child of the printout element.
scale O boolean If False (default), the image is cut to box dimensions. If True, the bitmap is scaled to the box.

barcode

Draw a bar code image.

Attributes:

Name Req Type Description
type M string Code128, Code39, or 2of5i.
value M string The text encoded with the bar code.
stripes M list of integers Precomputed bar code - comma-delimited sequence of bar/space widths, starting from space for leading quiet zone.
module O number X dimension, in mils (1/1000inch). Default: 10.0.
vertical O boolean If True, the image is rotated 90 degrees clockwise.

outline

A bookmark in the document navigation pane.

Some printout rendering front-ends may support navigation inside document contents. (For example, PDF documents have an outline pane.) The outline element defines an entry in such navigation tree.

Attributes:

Name Req Type Description
name M string

An identifier for the bookmark.

Must be unique within the document.

title M string Caption text for the outline tree.
level O integer

An outline nesting level.

The outermost level (default) is 1. Nested levels have bigger numbers.

The level number must be increased by one when a nested level is created: going from 1 to 3 without 2 is an error.

closed O boolean True to display the outline closed at this entry (i.e. hide all nested levels).
x O dimension Horizontal position (Default: 0).
y O dimension Vertical position (Default: 0).