How-to: File input / output

ArupCompute supports calculations that accept file inputs and produce file outputs. To ensure correct handling, these files must be accompanied by specific metadata, as outlined on this page.

tip

For definitions of ArupComputeResult and ArupComputeResultItem, see this page.

Inputs

To specify an input as a file, use the isFile attribute and set its value to True. Additionally, define the allowed file types using the fileTypes attribute. File types must include the "." prefix (e.g., ".txt"). ArupCompute will only accept files that match the specified type(s) for your calculation. To allow multiple file types, separate them with commas—for example: ".xlsx, .csv".

Below is an example of a calculation that takes in a text file and then reads the lines and the name of the file into an ArupComputeResult object:

def fileInputExample(inputFile: str) -> ArupComputeResult:
    """Single file input

    Takes in a single text file and return file content and file name

    Args:
        :inputFile: input text file with any content
            isFile: true
            fileTypes: .txt

    Returns:
        :lines: the lines in the file
        :name: name of the file
    """
    with open(inputFile, 'r') as f:
        lines = f.readlines()
        name = f.name
    acr = ArupComputeResult()
    outputLine = ArupComputeResultItem()
    outputLine.value = lines
    outputLine.laTeX = "lines"
    outputLine.symbol = "lines"
    acr.arupComputeResultItems.append(outputLine)

    outputName = ArupComputeResultItem()
    outputName.value = name
    outputName.laTeX = "name"
    outputName.symbol = "name"
    acr.arupComputeResultItems.append(outputName)
    return acr

Below is the example of calculation that updates an Excel file of type .xlsx or .xls by appending a list of values and returns the modified file as an .xlsx output using ArupComputeResult.

def updateExcel(excelSheet : str, listValues : List[int]) -> ArupComputeResult:
    """Update Excel

    A calc that takes in an Excel file and a list of inputs. Adds the inputs to the Excel file and then returns the Excel file

    Args:
        :excelSheet: Excel sheet to be updated
            isFile: true
            fileTypes: .xlsx,.xls
        :listValues: Values that are to be added to sheet

    Returns:
        :excelOutput: The excel output file
            isFile: true
            fileType: .xlsx
    """
    try:
        wb = openpyxl.load_workbook(excelSheet)
    except Exception as ex:
        raise Exception(f"Error reading Excel from local path: {ex}")

    # Step 2: Write values
    ws = wb.active
    start_row = ws.max_row + 1
    for idx, val in enumerate(listValues):
        ws.cell(row=start_row + idx, column=1, value=val)

    # Step 3: Save output to temp file
    temp_dir = tempfile.gettempdir()
    output_file = os.path.join(temp_dir, "excelOutput.xlsx")
    wb.save(output_file)

    # Step 4: Wrap in ArupComputeResult
    acr = ArupComputeResult()
    rfi = ArupComputeResultFileItem()
    rfi.fileName = "excelOutput.xlsx"
    rfi.fileData = output_file
    rfi.description = "Updated Excel file"
    rfi.fileType = ".xlsx"
    acr.arupComputeResultFileItems.append(rfi)

    return acr

Outputs

ArupCompute enables you to return files as outputs from your calculations, either as a single file or alongside other outputs within an ArupComputeResult object. To ensure ArupCompute recognizes and handles file outputs correctly, you must annotate the output with the isFile attribute set to True and specify the file type using the fileType attribute (including the leading dot, e.g., .txt). Note that only one file type can be defined per output.

Below example demonstrates how to return a file from a calculation in ArupCompute. It writes the given text to a .txt file and returns it as an output. The function uses the ArupComputeResultFileItem object to include metadata such as fileName, fileData (the file path), fileType, and a description. This file item is then appended to the arupComputeResultFileItems list of the ArupComputeResult object.

def single_file_output(text: str) -> ArupComputeResult:
   """Single file output

   Writes the provided text to a file and returns it as an output file.

   Args:
      :text: Text to be written to the file

   Returns:
      :outputFile: Output file containing the text
        isFile: true
        fileType: .txt
   """
   import os
   import tempfile

   temp_dir = tempfile.gettempdir()
   output_file = os.path.join(temp_dir, "outputFile.txt")
   with open(output_file, 'w', encoding='utf-8') as f:
      f.write(text)

   acr = ArupComputeResult()
   file_item = ArupComputeResultFileItem()
   file_item.fileName = "outputFile.txt"
   file_item.fileData = output_file
   file_item.fileType = ".txt"
   file_item.description = "Output file containing the provided text"
   acr.arupComputeResultFileItems.append(file_item)
   return acr

The below function demonstrates how to return a file output by directly providing the file path as a string. It writes the input text to a .txt file and returns the path to that file.

def single_file_output_path(text: str) -> str:
   """Single file output (file path only)

   Writes the provided text to a file and returns the file path.

   Args:
      :text: Text to be written to the file

   Returns:
      :outputFile: Path to the output file
        isFile: true
        fileType: .txt
   """
   import os
   import tempfile

   temp_dir = tempfile.gettempdir()
   output_file = os.path.join(temp_dir, "output_file.txt")
   with open(output_file, 'w', encoding='utf-8') as f:
      f.write(text)
   return output_file

Best Practices:

• Always set isFile: true and specify fileType in the docstring for file outputs.
• Use ArupComputeResultFileItem to provide metadata such as file name, path, type, and description.
• Add each file output to the arupComputeResultFileItems list of your result object.

This ensures that ArupCompute can correctly identify, process, and make your output files available for download or further use by clients.