Skip to content

Import python executables

This page provides a thorough overview of the "imports" property in OpenReport, including setup, usage, examples and the schema generation feature.

Back to homepage

Overview

The "imports" property allows OpenReport to discover and apply user's Python functions and classes. When "imports" is specified at the document level, OpenReport parses the referenced file, extracts all callable objects from its import statements, and makes them available as "python_executable" values in "source" instances throughout the document.

Without "imports", OpenReport has no knowledge of which Python functions are available and cannot resolve "python_executable" references. The "imports" property is the mechanism that connects user-defined Python code to the OpenReport document generation pipeline.

How it works

Step 1: Create the imports file

Create a Python file (e.g., imports.py) that contains from ... import ... statements pointing to your own functions and classes:

from my_analysis.tables import generate_sales_table
from my_analysis.figures import plot_revenue_chart
from my_analysis.text import generate_executive_summary

Each imported name becomes a valid "python_executable" value. In this example, the following values become available: generate_sales_table, plot_revenue_chart and generate_executive_summary.

Step 2: Update the schema

OpenReport provides a CLI command to generate a resolved JSON schema based on the imports file. The resolved schema enables IDE autocomplete for "python_executable" names and their parameters.

Run the following command:

python -m OpenReport update-schema path/to/imports.py

This produces a resolved schema file named OpenReportSchema_<imports_file_name>.json in the current working directory. The schema needs to be generated once, or whenever the imports file changes. After this, all imported functions and their parameters become available for autocomplete when editing the "python_executable" value in YAML files.

Using the resolved schema in your IDE

After generating the resolved schema, configure your IDE to use it instead of the base schema:

PyCharm / IntelliJ IDEA (with yamlconfig-idea plugin):

  1. Go to File > Settings > Languages & Frameworks > Schemas and DTDs > JSON Schema Mappings
  2. Add a new mapping pointing to the generated OpenReportSchema_imports.json
  3. Set the file pattern to match your YAML files (e.g., *.yaml)

For example, using the imports file from Step 1, generate_sales_table has signature generate_sales_table(region, year) and plot_revenue_chart has signature plot_revenue_chart(year, quarter="Q1"). After running python -m OpenReport update-schema imports.py:

  • python_executable autocompletes to generate_sales_table, plot_revenue_chart or generate_executive_summary.
  • When python_executable: generate_sales_table is selected, the schema requires region and year parameters.
  • When python_executable: plot_revenue_chart is selected, the schema requires year parameter (quarter is optional since it has a default value).

Step 3: Reference the imports file in YAML

Specify the "imports" property at the document level, pointing to your imports file:

document:
  name: report.docx
  imports: "imports.py"
  structure:
    - text:
        source:
          output: text
          source_type: python
          python_executable: generate_executive_summary
          year: 2025

Step 4: Generate the document

from OpenReport import OpenReportDocumentGenerator

generator = OpenReportDocumentGenerator(
    yaml_input="report.yaml",
    output_format="word",
    save_location="./"
)
generator.process()

Back to top

YAML examples

With loops

Functions referenced by "python_executable" can receive iterator and parameter values as inputs:

document:
  name: multi_portfolio_report.docx
  imports: "imports.py"
  parameters:
    - parameter:
        parameter_name: cohort
        parameter_type: manual
        parameter_value: June
  structure:
    - heading:
        body: Portfolio Backtesting Report
        level: 1
    - loop:
        iterator_name: portfolio
        iterator_type: manual
        iterator_values: [Mortgages, SME, Rural]
        iterator_applicable:
          - heading:
              body: "Results for @iterator{portfolio}"
              level: 2
          - table:
              source:
                output: table
                source_type: python
                python_executable: generate_results_table
                portfolio: "@iterator{portfolio}"
                cohort: "@parameter{cohort}"
              table_style: Light List Accent 1
          - figure:
              source:
                output: figure
                source_type: python
                python_executable: generate_figure
                portfolio: "@iterator{portfolio}"
                cohort: "@parameter{cohort}"
              figure_width: page

In this example, the loop iterates over three portfolios. For each iteration, the generate_results_table and generate_figure functions are called with the current iterator value and the parameter value as inputs.

With document loops

The "imports" property can also be specified at the "document_loop" level:

document_loop:
  iterator_name: region
  iterator_type: manual
  iterator_values: [EMEA, APAC, Americas]
  imports: "imports.py"
  iterator_applicable:
    - document:
        name: "@iterator{region}_report.docx"
        structure:
          - heading:
              body: "@iterator{region} Regional Report"
              level: 1
          - table:
              source:
                output: table
                source_type: python
                python_executable: generate_sales_table
                region: "@iterator{region}"
                year: 2025

Back to top

Function requirements

The imported functions must follow these conventions depending on the "output" type:

Text functions must return a string: 

def generate_executive_summary(year, quarter):
    """Generate executive summary text.

    Args:
        year: The fiscal year
        quarter: The quarter (Q1, Q2, Q3, Q4)
    """
    return f"In {quarter} of {year}, the company achieved record growth..."

Table functions must return a pandas DataFrame: 

import pandas as pd

def generate_sales_table(region, year):
    """Generate sales data table.

    Args:
        region: The sales region
        year: The fiscal year
    """
    data = {"Month": ["Jan", "Feb", "Mar"], "Sales": [100, 150, 200]}
    return pd.DataFrame(data)

Figure functions must save a figure to a file and return the file path as a string: 

import matplotlib.pyplot as plt

def plot_revenue_chart(year):
    """Plot revenue chart.

    Args:
        year: The fiscal year
    """
    fig, ax = plt.subplots()
    ax.bar(["Q1", "Q2", "Q3", "Q4"], [250, 300, 280, 350])
    ax.set_title(f"Revenue {year}")
    output_path = f"output/revenue_{year}.png"
    plt.savefig(output_path)
    return output_path

Array functions (for loop iterators) must return a list: 

def get_portfolio_names():
    """Return list of portfolio names."""
    return ["Mortgages", "SME", "Rural"]

Back to top

Important notes

  • All imports in the imports file must be resolvable from the Python environment where OpenReport is run. Ensure the modules are installed or the Python path includes the relevant directories.
  • The "imports" property path can be absolute or relative to the current working directory.
  • All parameter values passed from YAML are strings. If your function expects other types (int, float, etc.), perform the conversion inside the function.
  • The "imports" property is optional.

Continue to Components generation

Back to top

Back to homepage