4. Using Files¶

This tutorial is based on example code which can be found in the TRAC GitHub Repository under examples/models/python.

Not every model input or output is a table. The runtime also supports files - images, documents, or any other binary content - as first-class inputs and outputs alongside tabular datasets.

Writing a file output¶

File inputs and outputs are defined with define_input() and define_output(), using a FileType in place of a schema. CommonFileTypes provides a set of ready-made file types for common formats, or a custom one can be built with define_file_type().

This example reads a tabular dataset and writes out an SVG chart built with Matplotlib:

src/tutorial/file_io_matplotlib.py¶

    def define_inputs(self) -> _tp.Dict[str, trac.ModelInputSchema]:

        quarterly_sales_schema = trac.load_schema(schemas, "profit_by_region.csv")
        quarterly_sales = trac.define_input(quarterly_sales_schema, label="Quarterly sales data")

        return { "quarterly_sales": quarterly_sales }

    def define_outputs(self) -> _tp.Dict[str, trac.ModelOutputSchema]:

        sales_report = trac.define_output(trac.CommonFileTypes.SVG, label="Quarterly sales report")

        return { "sales_report": sales_report }

To write a file output, use put_file_stream(), which gives a writable binary stream for the output. The stream must be used in a with block, as shown here where the Matplotlib figure is saved directly into the output stream.

    def run_model(self, ctx: trac.TracContext):

        matplotlib.use("agg")

        quarterly_sales = ctx.get_pandas_table("quarterly_sales")

        regions = quarterly_sales["region"]
        values = quarterly_sales["gross_profit"]

        fig = plt.figure()

        plt.bar(regions, values)
        plt.title("Profit by region report")
        plt.xlabel("Region")
        plt.ylabel("Gross profit")

        with ctx.put_file_stream("sales_report") as sales_report:
            plt.savefig(sales_report, format='svg')

        plt.close(fig)

There is also a put_file() method that takes the file content directly as bytes, for cases where the whole file is already available in memory rather than being written incrementally to a stream.

Reading and writing files¶

Reading a file input works the same way, in reverse. This example reads a PowerPoint template as a file input, along with a tabular dataset, and produces a new PowerPoint file with a chart added to it:

src/tutorial/file_io_powerpoint.py¶

    def define_inputs(self) -> _tp.Dict[str, trac.ModelInputSchema]:

        quarterly_sales_schema = trac.load_schema(schemas, "profit_by_region.csv")
        quarterly_sales = trac.define_input(quarterly_sales_schema, label="Quarterly sales data")
        report_template = trac.define_input(trac.CommonFileTypes.POWERPOINT, label="Quarterly sales report template")

        return {
            "quarterly_sales": quarterly_sales,
            "report_template": report_template }

    def define_outputs(self) -> _tp.Dict[str, trac.ModelOutputSchema]:

        sales_report = trac.define_output(trac.CommonFileTypes.POWERPOINT, label="Quarterly sales report")

        return { "sales_report": sales_report }

get_file_stream() gives a readable binary stream for a file input, again used in a with block. The runtime guarantees that the file’s recorded mime type and extension match what was declared in define_input(), but does not inspect or guarantee anything about the content of the file itself.

    def run_model(self, ctx: trac.TracContext):

        quarterly_sales = ctx.get_pandas_table("quarterly_sales")

        with ctx.get_file_stream("report_template") as report_template:
            presentation = pptx.Presentation(report_template)

        slide = presentation.slides.add_slide(presentation.slide_layouts[5])

        title_frame = slide.shapes[0].text_frame
        title_frame.text = 'Profit by Region Report'

        # define chart data ---------------------
        chart_data = CategoryChartData()
        chart_data.categories = quarterly_sales["region"]
        chart_data.add_series('Gross Profit', quarterly_sales["gross_profit"])

        # add chart to slide --------------------
        x, y, cx, cy = Inches(2), Inches(2), Inches(6), Inches(4.5)
        slide.shapes.add_chart(XL_CHART_TYPE.COLUMN_CLUSTERED, x, y, cx, cy, chart_data)

        with ctx.put_file_stream("sales_report") as sales_report:
            presentation.save(sales_report)

As with writing, there is a get_file() method that returns the whole file as bytes, for cases where streaming isn’t needed.