filemaker

Built-in module that wraps FileMaker API for Python.

Overview#Back to top

filemaker has six types for FileMaker data types, three types for text formatting, calculation environment type, and two array-like types to work with the internal SQL engine.

filemaker.Text         filemaker.Style    filemaker.Environment
filemaker.Number       filemaker.Font     filemaker.Row
filemaker.Date         filemaker.Color    filemaker.RowSet
filemaker.Time
filemaker.Timestamp
filemaker.Container

The module also has a few minor types for Container, Row, and RowSet iterators, but they're absolutely trivial; I don't document them.

All these types are native FileMaker types with a thin Python wrapper.

FileMaker also has a few global methods:

evaluate()          run_script()        api_version()
execute_sql()       run_when_idle()     applicatio()
execute_sql_2()                         version()

The first three are same as the methods of the Environment type (they actually create a temporary istance to run), one calls scripts, one uses idle time, and three provide information about FileMaker application type, version, and plug-in API version.

Modifiable, read-only, and volatile instances#Back to top

An important thing about FileMaker types, especially data types, is that everything you create yourself is modifiable, but everything you get from FileMaker is read-only. (But you can always make a modifiable copy if necessary.) In addition, the passed parameters are not only read-only, but volatile, which means you should not keep them between function calls. (Again, you can make a stable copy if you need to.) See more about this in Parameters.

A few exceptions: Font is always read-only, Style is always modifiable, Environment just has nothing to modify, and RowSet cannot be created; you can only get it from execute_sql_2(), so it is always read-only.

Supported Python types#Back to top

filemaker module automatically converts basic Python types: None, bool, str, unicode, int, long, float and temporal types from the datetime module: date, time, datetime, and timedelta. This means your functions can safely return unicode or datetime.date; the plug-in will change them into a matching FileMaker type. Here's a list of which type matches which:

filemaker.Text str, unicode; None filemaker.Number int, long, float; bool filemaker.Date datetime.date filemaker.Time datetime.date, datetime.timedelta filemaker.Timestamp datetime.datetime

Container has no compatible Python type and has to be constructed programmatically.

Type conversion#Back to top

FileMaker is known for its flexible type system and filemaker tries to follow the suit.

To convert Python to FileMaker or to convert between FileMaker types, create a new instance of the target type and pass it what you want to convert as a value:

>>> from filemaker import Text
>>> t = Text(123)
>>> str(t)
'123'

This example sets t to a text value of 123, i.e. a string ‘123.’ To have more control over the conversion use additional options. One of important options is locale; you can specify it whenever you convert from text or to text:

>>> from filemaker import Text, ENGLISH_LOCALE, GERMAN_LOCALE
>>> t = Text(123.456, ENGLISH_LOCALE)
>>> str(t)
'123.456'
r>> u = Text(123.456, GERMAN_LOCALE)
>>> str(u)
'123,456'

FileMaker locale support is pretty basic; if you need a serious tool, look elsewhere.

To convert FileMaker to Python use str(), unicode(), bool(), int(), long(), and float() to convert to the corresponding Python types. To convert to Python datetime types use instance methods date(), time(), datetime() and timedelta().

When you convert between text and non-text type (i.e. you either parse a text value as a number or a date or write a non-text value as a text), these conversions use the locale of the current file. To have a more precise control over the locale use a compatible FileMaker type as an intermediary. For example:

>>> from filemaker import Text, Date, GERMAN_LOCALE
>>> t = Text('4/7/2010')
>>> t.date()
datetime.date(2010, 4, 7)
>>> Date(t, locale=GERMAN_LOCALE).date()
datetime.date(2010, 7, 4)

The first direct conversion to date used the current file locale, which happened to be English (month-day-year); the second used an itermediate Date with an explicit German locale (day-month-year).

Check the documenation on specific classes for more information.

Module contents#Back to top

filemaker is a rather larger module, so I describe each type and the global methods in separate sections:

The module also includes three iterator classes for Container, Row, and RowSet, but they're standard trivial iterators; I do not document them.