Skip to content

ExcelAddin

Represents an Excel add-in deployment on Datatailr.

An Excel add-in exposes Python functions as Excel worksheet functions, allowing users to call server-side computations directly from Excel spreadsheets.

At construction time, type annotations on @addin.expose(...) functions in the entrypoint source file are validated. Only plain int, float, list, bool, and str are allowed (plus Queue on a parameter named queue for streaming functions). Invalid annotations raise ValueError before the job definition is built.

Create the Addin object in the same module as the entrypoint function. The platform does not call the entrypoint. It imports the module of the entrypoint and starts the Addin object that this module creates.

Example
# options_pricer/addin.py
from math import exp, log, sqrt

from datatailr.excel import Addin
from scipy.stats import norm

addin = Addin("Options Pricer", "Option pricing functions")

@addin.expose(
    description="Black-Scholes call price",
    help="Give the spot, strike, volatility, rate and years to expiry",
)
def price_option(
    spot: float, strike: float, vol: float, rate: float, expiry: float
) -> float:
    d1 = (log(spot / strike) + (rate + vol**2 / 2) * expiry) / (
        vol * sqrt(expiry)
    )
    d2 = d1 - vol * sqrt(expiry)
    return spot * norm.cdf(d1) - strike * exp(-rate * expiry) * norm.cdf(d2)

def main(port=8080, ws_port=8000):
    addin.run(port, ws_port)

Put the deploy script outside the add-in package:

# deploy.py
from datatailr import ExcelAddin
from options_pricer.addin import main

excel_addin = ExcelAddin(
    name="Options Pricer",
    entrypoint=main,
    python_requirements=["scipy"],
)
excel_addin.save()

In Excel, the function is =OPTIONSPRICER.PRICEOPTION(...).

Parameters:

  • name

    (str) –

    Display name for the add-in.

  • entrypoint

    (Callable) –

    The callable (function) that starts the add-in server. Define it in the module that creates the Addin object. Its source file is scanned for @*.expose(...) functions; parameter and return annotations must use only int, float, list, bool, str, or Queue (on a parameter named queue).

  • environment

    (Environment | None, default: DEV ) –

    Target environment for the deployment.

  • image

    (Image | None, default: None ) –

    Pre-configured container Image.

  • run_as

    (str | User | None, default: None ) –

    User or username to run the add-in as.

  • resources

    (Resources | None, default: None ) –

    CPU, memory, and optional GPU memory for the container. Defaults to Resources() (128 MB, 0.25 CPU, no GPU request). Set GPU memory with vram, using the same size strings as memory. If vram is omitted, the job JSON omits vram.

  • acl

    (ACL | None, default: None ) –

    Access control list.

  • python_version

    (str, default: '3.12' ) –

    Python version for the container image.

  • python_requirements

    (str | list[str], default: '' ) –

    Python dependencies (see Image).

  • build_script_pre

    (str, default: '' ) –

    Dockerfile commands to run before installing requirements.

  • build_script_post

    (str, default: '' ) –

    Dockerfile commands to run after installing requirements.

  • build_secret_keys

    (list[str] | None, default: None ) –

    Names of build secrets exposed to the build scripts (see Image).

  • env_vars

    (dict[str, str | int | float | bool] | None, default: None ) –

    Environment variables passed to the running container.

  • get_existing

    (bool, default: False ) –

    If True, update an existing job definition.

  • version

    (str | int | None, default: None ) –

    The version of the job to get.

  • app_section

    (str, default: '' ) –

    The section to which the app belongs. If not provided, the app will be assigned to the default section. This affects the app launcher page.

  • budget

    (Budget | str | None, default: None ) –

    Optional spend budget as Budget("name") or a name str. Will be set to the 'default' budget if not provided.