Welcome to OpenReport Documentation

Overview

This is the homepage of OpenReport documentation. Here, you will find links to various sections of the documentation to guide you through the setup, usage, and advanced topics.

Feel free to navigate through these sections to learn more about the project and its capabilities.

Installation

OpenReport Base is available on PyPI. Install it using pip:

pip install openreport-base

Or using Poetry:

poetry add openreport-base

Requirements: Python 3.12 or higher.

After installation, verify it works:

from OpenReport import OpenReportDocumentGenerator

OpenReport Base includes support for:

Text and Headings
Mathematical expressions
Bullet lists
Page breaks
Document styling and parameters
Table of contents
PDF export

Recommended IDE Plugin

For enhanced YAML editing experience, we recommend installing the yamlconfig-idea plugin:

Open PyCharm/IntelliJ IDEA
Go to File → Settings (or PyCharm → Preferences on macOS)
Navigate to Plugins in the left sidebar
Click Marketplace tab
Search for "yamlconfig-idea"
Click Install next to the plugin
Restart your IDE when prompted

This plugin provides enhanced YAML syntax highlighting, validation, and autocompletion features that improve the OpenReport YAML specification editing experience.

Back to top

What OpenReport can do?

OpenReport is a powerful YAML-based tool for creating fully automated and parameterized documents. OpenReport streamlines the integration of user's own analysis and custom formatting into structured reports.

Features

Parses a YAML specification file, which can be intuitively created using autocomplete.
Supports essential document components including texts, headings, tables and figures:
components can be generated dynamically based on the user's own analysis.
components can be parameterized specifying text and heading styling, table formatting, and figure embedding.
Supports user-defined parameters for enhanced flexibility.
Supports loop for adding repetitively (a set of) similar components.
Supports loop for document batch creation.
Generates fully formatted Word or PDF documents from a YAML specification file.

The YAML file defines a structured sequence of actions, including generation and formatting rules, which OpenReport converts into ready-to-use document.

Back to top

Functionality

OpenReport offers a structured and reusable approach to document creation. Using an intuitive YAML-based framework, it allows users to define the structure, formatting, and content of automated reports. From a YAML specification file, OpenReport generates a Word (.docx) or PDF document containing a well-organized set of parameterized elements, including:

Text
Headings
Tables (with captions)
Figures (with captions)
Mathematical expressions
Bullet lists
External Word files
Automatically generated:
Table of contents
List of figures
List of tables

A valid YAML file must contain 'document', 'name', and 'structure' keys. For example:

document:
  name: document.docx
  structure:
    - heading: 
        # heading attributes
    - text:
        # text attributes
    - table:
        # table attributes
    - figure:
        # figure attributes

This specification initiates a document with attributes 'name' (document.docx) and 'structure' which lists all the document components. The order components appear under 'structure' reflects the order in the document. Component attributes specify the formatting and generation rules.

Back to top

Component formatting

Each component supports custom formatting. For example:

- text:
    body: Hello World!
    font: Calibri
    size: 9

This specification adds text "Hello World!" to the document with fixed attributes 'size' (9) and 'font' (Calibri).

To avoid repeating the same formatting on every component, OpenReport supports default styles at the document level. For example:

document:
  name: report.docx
  document_style:
    default_text_style:
      font: Calibri
      size: 11

This applies Calibri font and size 11 to all text components automatically. Individual components can still override the defaults. See Components appearance for details.

The full formatting functionality is available at: Components.

Back to top

Component generation

Components can be dynamically generated using the 'source' key. For example:

- figure:
    source:
      output: figure
      source_type: local
      location: 'inputs/figure.jpg'

This specification adds figure that is stored locally at 'inputs/figure.jpg' to the document.

The generation mode can be 'local' (for locally stored files) or 'python' (for output generated by python code). With python mode any kind of user's own analysis can be incorporated directly in the desired place of the document. For example:

- table:
    source:
      output: table
      source_type: python
      python_executable: generate_table
    table_font: Times New Roman
    table_font_size: 9
    caption:
      body: This is a table caption

This specification adds table to the document. The table is an output of user-defined function 'generate_table'. The table's text is fixed with attributes 'table_font_size' (9) and 'table_font' (Times New Roman). The table's caption is "This is a table caption".

The inputs for user-defined function can be specified directly under 'source'. For example:

- figure:
    source:
      output: figure
      source_type: python
      python_executable: plot_sales_per_year
      country_name: France

This specification adds figure to the document. The figure is an output of user-defined function 'plot_sales_per_year' with input parameter 'country_name' (France). This is equivalent to:

fig = plot_sales_per_year(country_name="France")

To use python executables, the "imports" property is specified at the document level and points to a Python file containing import statements of the user's functions:

from my_analysis import generate_table
from my_analysis import plot_sales_per_year

Each imported callable becomes a valid "python_executable" value. For the full setup guide see Import python executables.

Text and heading components can also be generated using AI. The "ai_prompt" property sends a prompt to a configured AI provider and uses the response as the component's body content:

document:
  name: report.docx
  ai_config:
    provider: openai
    model: gpt-4o-mini
  structure:
    - text:
        ai_prompt: "Write a professional paragraph about renewable energy trends."
        font: Calibri
        size: 11

For the full setup guide see AI Content Generation.

The full generation mode functionality is available at: Components generation.

Back to top

Parameters

OpenReport allows to declare a parameter and assign it a value. For example:

- parameter: 
    parameter_name: year
    parameter_type: manual
    parameter_value: 2025

This specification declares parameter (year). User manually assigns it a value (2025). The declared parameter can be referenced throughout the document using the @parameter{parameter_name} format:

- text:
    body: Happy New @parameter{year} Year!
    colour: #ffffff

This specification adds text "Happy New 2025 Year!" to the document with attribute 'colour' in HEX format (#ffffff).

Parameters can be defined using 'source' key. For example:

- parameter:
    parameter_name: total_sales
    parameter_type: source
    source:
      output: text
      source_type: python
      python_executable: calculate_total_sales

This specification declares parameter (total_sales). The value of parameter is an output of user-defined function 'calculate_total_sales'. The parameter value can be addressed within the rest of the document:

- text:
    body: Total sales for year @parameter{year} is @parameter{total_sales}.

If 'calculate_total_sales' outputs 250,000, the document will contain:

Total sales for year 2025 is 250,000.

The full parameter functionality is available at: Parameters.

Back to top

Iterations

OpenReport allows to declare a loop and add repetitively (a set of) similar objects using the @iterator{iterator_name} format. For example:

- loop:
    iterator_name: year
    iterator_type: manual
    iterator_values: [2025, 2026]
    iterator_applicable:
      - text:
          body: Total sales for year @iterator{year} have increased.

This specification declares iterator (year). User manually specifies iterator values (2025, 2026). The document will contain:

Total sales for year 2025 have increased.
Total sales for year 2026 have increased.

Loops can be defined using 'source' key. For example:

- text:
    body: "The sales per month are:"
- loop:
    iterator_name: sales_month_i
    iterator_type: source
    source:
      output: array
      source_type: python
      python_executable: calculate_sales_per_month 
    iterator_applicable:
      - text: 
          body: " - @iterator{sale_month_i} EUR"

This specification declares iterator (sales_month_i). The values of the iterator are an output of user-defined function 'calculate_sales_per_month'. If the script outputs [10, 20, 30], the document will contain:

The sales per month are:
 - 10 EUR
 - 20 EUR
 - 30 EUR

Nested loops are also supported. The full loop functionality is available at: Iterations.

Back to top

Document Iterations

OpenReport enables batch document creation: For example:

document_loop:
  iterator_name: country
  iterator_type: manual
  iterator_values: [Germany, France]
  iterator_applicable: 
    - document:
        name: @iterator{country}_sales_report.docx
        structure:
          - heading: 
              body: @iterator{country}
          - text: 
              body: "The figure below shows sales per month for @iterator{country}:"
          - figure:
              source:
                output: figure
                source_type: python
                python_executable: plot_sales_per_year
                country_name: @iterator{country}

This specification creates two documents (Germany_sales_report.docx and France_sales_report.docx). Each document has a heading specifying the country name, a text and a figure generated by user-defined function 'plot_sales_per_year' with input parameter 'country_name'. The example of output for Germany is:

The example of output for France is:

The full document loop functionality is available at: Documents iteration.

Back to top