YOUSEFUL / FILEMAKER

YsflPython — function reference

Function prefix YsflPy_, 15 functions. Runs Python from FileMaker either in process (CPython loaded into FileMaker through python3.dll, the stable ABI, so any Windows CPython 3.8 or later works) or out of process through python.exe.

Modes

mode	engine	state between calls	notes
`inproc` (default when a Windows CPython is installed)	CPython inside FileMaker	a persistent namespace until `YsflPy_Reset`	full standard library and site-packages of that installation; timeouts interrupt through a trace hook
`worker`	one `python.exe` kept alive per session	persists until `Reset`, `Stop`, a timeout or a crash	isolated from FileMaker's process
`process`	a fresh `python.exe` per call	none	safest isolation

The installation is found through home=<dir with python3.dll> / python=<python.exe>, the YSFL_PYTHON environment variable, the registry (Software\Python\PythonCore), the per-user Programs\Python folder, or PATH. MSYS2/Cygwin Pythons are skipped (no python3.dll). The python.exe host script is written to %LOCALAPPDATA%\Youseful\hosts\ysflpy_host.py.

Options (per call or via Configure)

mode=inproc|process|worker, timeout=<sec> (default 60), home=<dir>, python=<path>, param=<text> (rest of the line; fm.param).

Functions

Function	Returns
`YsflPy_Run ( code ; {options} )`	the value of the last expression statement (`1 + 2` → `3`; `dict`/`list` as JSON; `None` → `""`; booleans `true`/`false`); when there is none, what `print` wrote
`YsflPy_RunFile ( path ; {options} )`	same, from a `.py` file
`YsflPy_Call ( function ; {argsJSON} ; {options} )`	calls a function defined earlier with a JSON array of arguments
`YsflPy_Set ( name ; value ; {type} )`	defines a variable; `text` (default), `number` (int or float), `bool`, `json`
`YsflPy_Get ( name )`	a variable's value
`YsflPy_Output`	printed output of the last call (stdout and stderr)
`YsflPy_Error`	full traceback of the last call
`YsflPy_Reset`	fresh namespace (imports stay loaded)
`YsflPy_Stop`	ends the worker process
`YsflPy_Configure ( options )`	session defaults
`YsflPy_Mode`	effective mode and interpreter location
`YsflPy_Version`	plugin, CPython version once initialised, python.exe path
`YsflPy_Register`, `YsflPy_LastError`, `YsflPy_LastErrorText`

Failures return ? ExceptionType: message; YsflPy_Error has the traceback.

Talking to FileMaker from the script

fm.evaluate ( expr ), fm.sql ( query ) (rows ¶, columns tab) and fm.param work in every mode.

Notes

In-process CPython is initialised once per FileMaker session and never finalised (CPython cannot be restarted safely); YsflPy_Reset clears the namespace instead.
Threads started by scripts keep running between calls in-process; prefer the worker for long-running or thread-heavy code.
The in-process timeout uses sys.settrace, which slows Python code while a timeout is set; use timeout=0 for CPU-bound scripts you trust.

Set Variable [ $r ; YsflPy_Run ( "import pandas as pd¶df = pd.read_csv(fm.param)¶df['amount'].sum()" ; "param=" & $csvPath ) ]
Set Variable [ $r ; YsflPy_Configure ( "mode=worker python=C:\Python313\python.exe" ) ]