PyRun

Call a Python function and return the result. This is the main way to Python from FileMaker.

Usage#Back to top

PyRun( module; callableOrObject {; arg1, arg2; ... } )

Arguments#Back to top

module

Python module name; can be a submodule name, e.g. os.path.

callableOrObject

Name of the function or the object. If the object is callable (this is tested with the standard callable() function), then PyRun() will try to call it with the passed arugments; else it will try to simply return the object itself. This parameter is case-sensitive.

arg1, arg2, ...

Optional arguments as required by the callable. If the object is not callable, the arguments are ignored.

Results and side effects#Back to top

Depends on the called function. The PyRun() itself may return the following errors:

  • ImportError if it cannot find or import the module.

  • AttributeError if the module has no function or object matching the value of the callableOrObject parameter. (Note that the value is case-sensitive.)

  • Exception if the result cannot be converted into FileMaker format.

See more about errors in PyFM in documetation for PyLastError.

Examples#Back to top

PyRun( "os"; "getcwd" )

This will run the getcwd method of the os module and return the current working directory.

The results depend on the platform and, as far as I understand, on the last operations with files. For example, if I insert a file into a container from my Documents folder on Windows and call this function, I'll get C:\Users\Mikhail\Documents.


PyRun( "os.path"; "sep" )

This will return the value of os.path.sep, which is the current path separator. On Mac OS X this will be /, on Windows \.


PyRun( "datetime"; "datetime.utcnow" )

This will return the current timestamp in the UTC (GMT) timezone. The precision of the result depends on the platform, I guess, but it should be up to at least milliseconds (FileMaker itself supports time precision up to a microsecond).


PyRun( "math"; "log"; 100 )

This will return the logarithm of 100 to the base e (the so-called natural logarithm) and will be a number approximately equal to 4.6. The e is the default base, but you can specify another:

PyRun( "math"; "log"; 100; 10 )

This one will return the logarithm of 100 to the base 10, which is 2.

Discussion#Back to top

This is the main plug-in function that allows to run any Python code and effectively write FileMaker plug-in functions in Python. The examples above are mostly toy examples because in practice the code you'll be calling will be especially written for FileMaker or at least tailored for it.

Part of the problem is that FileMaker can only call functions, while Python is object-oriented. There are some directly accessible functions (or classmethods, like datetime.utcnow() from the datetime module), but in most cases you'll need to create an object and then call its methods. It's not difficult to wrap this up into a function-based API, of course, but such API is not readily available; one has to write it first.

Another part of the problem is passing parameters. The plug-in doesn't convert the passed parameters into FileMaker format, but adds a thin wrapper around them and exposes this as a type, for example, filemaker.Text, filemaker.Date, etc.

Sometimes these parameters will work as they are; for instance, filemaker.Number supports a good part of the Python numeric protocol and thus can often be used as is; see the math examples above. But other types are not that compatible. For example, if you try to call os.path.isdir(), it won't work:

PyRun( "os.path"; "isdir"; "C:\Users" )

The result will be ? and PyLastError will return TypeError: coercing to Unicode: need string or buffer, filemaker.Text found. As you see, this happens because the function expects a string or a buffer, but receives filemaker.Text and cannot figure how to convert it to Unicode.

A simple adapter for this function would look like that:

import os.path
def is_directory(path):
    return '\r'.join(os.path.isdir(unicode(path)))

The \r separator (i.e. the CR char, code 13, default line separator in Mac OS Classic) is the native native FileMaker line separator and if you need to separate lines, it's better to use this one. Some FileMaker functions do understand the more common \n separator (e.g. GetValue()` or any other Value function), but some functions do not, in particular the functions that work with the placeholder.

The plug-in provides a safeguard for this and replaces all \n with \r, but if you use \r from the beginning, the result will get into FileMaker slightly faster.

If you save this as mymodule.py and put the file where the plug-in can find it, you'll be able to call your new function just fine:

PyRun( "mymodule"; "is_directory"; "C:\Users\" )

Of course, there's much more to it; please see the tutorial for all the detals.