Python API

Function decorator

@xllify.fn()

Register a Python function for Excel.

@xllify.fn(name, description="", category="", parameters=None, return_type="")
def my_function(...):
    ...

Arguments:

• name (str) - Excel function name (e.g., "xllipy.MyFunc")

• description (str) - Function description (defaults to docstring)

• category (str) - Excel function category

• parameters (list) - List of Parameter objects (optional)

• return_type (str) - Return type hint (optional)

Example:

example.py

@xllify.fn("xllipy.Calculate", category="Math", description="Square a number")
def calculate(x: float) -> float:
    return x * x

Parameter metadata

Use Parameter objects for detailed parameter info:

example.py

from xllify import fn, Parameter

@fn("xllipy.Divide",
    parameters=[
        Parameter("numerator", type="number", description="Number to divide"),
        Parameter("denominator", type="number", description="Number to divide by")
    ])
def divide(numerator: float, denominator: float) -> float:
    if denominator == 0:
        raise ValueError("Cannot divide by zero")
    return numerator / denominator

Parameter fields:

• name (str) - Must match function argument name

• type (str) - "number", "string", "boolean", or "array"

• description (str) - Parameter description

• optional (bool) - Whether parameter is optional

• default (any) - Default value

Type mapping

Excel Type	Python Type
Number	float
String	str
Boolean	bool
Range	List[List[Any]]
Empty cell	None

Arrays

Excel ranges become 2D lists:

example.py

@xllify.fn("xllipy.SumRange")
def sum_range(data: list) -> float:
    total = 0
    for row in data:
        for cell in row:
            if isinstance(cell, (int, float)):
                total += cell
    return total

Usage: =xllipy.SumRange(A1:C10)

Error handling

Raise exceptions to return errors to Excel:

example.py

@xllify.fn("xllipy.ValidatePositive")
def validate_positive(x: float) -> float:
    if x <= 0:
        raise ValueError("Number must be positive")
    return x

Excel shows: #ERROR: Number must be positive

Type definitions

types.py

from xllify import CellValue, Matrix, ExcelValue

CellValue = Union[float, bool, str, None]
Matrix = List[List[CellValue]]
ExcelValue = Union[CellValue, Matrix, Any]

• CellValue: A single Excel cell value — can be a number (float), boolean, string, or None (displays as empty cell)

• Matrix: A 2D array of cell values (list of lists), where each cell is a CellValue

• ExcelValue: Any value that can be returned to Excel (scalar, matrix, or pandas DataFrame)

Example returning a matrix:

example.py

from xllify import Matrix

@xllify.fn("xllipy.GetData")
def get_data() -> Matrix:
    return [
        [1.0, True, "hello"],
        [2.0, False, None],  # None displays as empty cell
        [3.0, None, "world"]
    ]