PythonReports Printout
| Version: | 0.10.0 |
|---|---|
| Date: | 10-oct-2021 |
Contents
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 text, line, rectangle, image, barcode, outline, and xref 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 image 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 image; 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 of the left side. |
| y | M | dimension | Vertical position of the element top. |
| 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, 2of5i, Aztec, QR-L, QR-M, QR-Q, or QR-H. |
| value | M | string | The text encoded with the bar code. |
| stripes | M | list of integers | Precomputed bar code: comma-delimited sequence of alternating mark and blank widths, starting from blank for leading quiet zone. With two-dimensional bar codes, one comma-delimited list represents one scan line of the code, and lists for several lines are separated with spaces. |
| module | O | number | X dimension, in mils (1/1000inch). Default: 10.0. |
| vertical | O | boolean | If True, the image is rotated 90 degrees clockwise. Ignored for 2D codes (Aztec and QR). |
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). |
xref
A hyperlink to an external resource or an outline entry.
xref elements contain one box element, and a sequence of text, line, rectangle, image, and barcode elements.
Attributes:
| Name | Req | Type | Description |
|---|---|---|---|
| type | M | string | url or outline. |
| target | M | string | An external resource URL for type url, or a name of an outline entry for type outline. |
| caption | O | string | Optional text to assign to the link. The text is not shown in PDF, but may be used by other front-ends. |
![[Python Powered]](./python-powered-w-120x40.png){kind=small}