Using Python Functions as UDF()

1. Overview

The built‑in UDF() function allows GS-Calc formulas to call Python modules and functions. This greatly expands functionality through Python’s scientific, financial, and graphics libraries.

You can pass numbers, text strings, ranges (as numeric arrays/matrices), or automatically saved CSV blocks to Python.

Python functions may return numbers, text, arrays, CSV blocks (parsed or unparsed), or images (binary data).

2. UDF() Syntax

UDF(module, function, type, parameter1, parameter2, ...)

module — full path to a Python module, e.g. "c:\my_modules\some_functions.py"
function — function name inside the module
type — expected return type (0–5):
- 0 — number
- 1 — numeric array/matrix
- 2 — text string (≤1024 chars)
- 3 — CSV block (no numeric parsing)
- 4 — CSV block (with numeric parsing)
- 5 — image (Python memoryview binary data)

Additional flags for type:

32 — pass ranges as CSV blocks
64 — pass ranges as CSV only if they contain non‑numeric/text cells

If neither flag is used, ranges are passed as numeric arrays (text ignored).

3. Example Python Module

e:\example.py:

def function1():
   return 10

def function2(a, b):
  return a + b

def function3(text):
   return 'A new text with ' + text + ' inserted in the middle'

def function4():
   csvdata = 'abc,def,ghi\n123,456,789'
   return csvdata

def function5(csvdata):
   return csvdata

def function6(csvFilePath):
   f = open(csvFilePath, 'rb')
   file_content = f.read()
   f.close()
   return file_content

def function7(imageFilePath):
   f = open(imageFilePath, 'rb')
   file_content = f.read()
   f.close()
   return bytearray(file_content)

4. Usage Examples in GS-Calc

UDF("e:\example.py", "function1", 0)

Returns 10.
UDF("e:\example.py", "function2", 0, 10, 20)

Returns the sum of two numbers.
UDF("e:\example.py", "function3", 2, "a word")

Returns a modified text string.
UDF("e:\example.py", "function4", 4)

Returns a CSV block that fills a 2×3 range.
UDF("e:\example.py", "function5", 4 + 32, b10:d10000)

Receives a CSV block and returns it for parsing.
UDF("e:\example.py", "function6", 4, "e:\some_csv_file.csv")

Loads a CSV file and returns its contents.
UDF("e:\example.py", "function7", 5, "e:\some_image.jpg")

Returns an image; GS-Calc displays it at original size.

1. Overview

2. UDF() Syntax

3. Example Python Module

4. Usage Examples in GS-Calc

Related Topics