py-appscript

6. Classes and enumerated types

The k ("keyword") namespace

For your convenience, appscript treats standard Apple event types and application-specific classes and enumerators as attributes of the appscript module's k ("keywords") attribute. Think of k as an infinitely large namespace that contains every possible name you could use. Examples:

from appscript import *

# AEM-defined data types:
k.boolean
k.unicode_text
k.list

# Application-defined class names:
k.document
k.window
k.disk

# Application-defined enumerators:
k.yes
k.no
k.ask

Occasionally an application defines a type or enumerator without providing it with a corresponding name name. In these cases, the value will be represented as a raw aem.AEType or aem.AEEnum object instead of a k attribute. The AEM documentation provides more information on these lower-level objects, should you need to use them.

Common AE types

AE typeappscript namePython type
typeNullk.nulltypes.NoneType
typeBooleank.booleanbool
typeIntegerk.integerint
typeFloatk.floatfloat
typeChar *k.stringstr
typeStyledText *k.styled_textstr
typeIntlText *k.international_textstr
typeUnicodeTextk.unicode_textstr
typeAEListk.listlist
typeAERecordk.recorddict
typeLongDateTimek.datedatetime.datetime
typeAliask.aliasmactypes.Alias
typeFileURLk.file_urlmactypes.File
typeFSRefk.file_refmactypes.File
typeFSS *k.file_specificationmactypes.File
typeDatak.databytes
typeObjectSpecifierk.referenceappscript reference
typeInsertionLock.location_referenceappscript insertion reference
typeTypek.type_classappscript keyword
typeEnumeratedk.enumeratorappscript keyword
unit types; e.g. typeFeetunit names; e.g. 'feet'mactypes.Units

(Note that types marked with '*' are officially deprecated and/or their use discouraged in Mac OS X. They remain supported to ensure backwards compatibility with older applications that may use them.)

Type mapping notes

While AEM-Python type conversions generally work quite seamlessly, it is sometimes useful to know some of the details involved, particularly when troubleshooting code that deals with older or buggy applications.

Numbers

When packing a Python int, appscript will pack it either as a 32-bit integer (most preferred), 64-bit integer, or 64-bit float (least preferred), depending on the value's size.

Strings

Note that while typeUnicodeText is formally deprecated in Mac OS X 10.4+ in favour of typeUTF8Text and typeUTF16ExternalRepresentation, it is still in common usage so appscript continues to use it to ensure the broadest compatibility with existing scriptable applications.

Filesystem references

The typeAlias AE type corresponds to the Carbon Alias type and represents a filesystem object. Appscript unpacks this type as a mactypes.Alias object. The typeFSRef, typeFSS and typeFileURL types correspond to Carbon FSRef, Carbon FSSpec and CoreFoundation CFURL types, and are used to represent a filesystem location. Appscript unpacks these AE types as mactypes.File objects. See the mactypes manual for more information.

While appscript unpacks all filesystem-related AE types as either mactypes.Alias or mactypes.File, don't forget that when asking an application to coerce a return value into a file type you must specify the exact file type (k.alias, k.file_url, k.file_ref, or k.file_specification) in the get command. For example, to get a mactypes.Alias object for the current user's home folder, you would usually use:

app('Finder').home.get(resulttype=k.alias)

Also be aware that some applications may not support coercions to all AE file types; you'll need to experiment to find out which coercions are supported.

Records

The typeAERecord AE type is a struct-like data structure containing zero or more properties. Appscript represents AE records as Python dicts. The keys in this dict are usually appscript keywords (e.g. k.name) representing appscript-style property names, although they may also be aem.AEType values or strings.

If a dict contains a k.class_ (or aem.AEType(b'pcls')) key, appscript will pack the remaining items into an AE record, then coerce it to the type specified by this 'class' property. Similarly, when unpacking an record-like AEDesc with a custom type code, appscript will unpack it as a hash with the type represented by a k.class_ entry.

Types and enumerators

The typeType and typeEnumerated AE types are unpacked as appscript keywords (e.g. k.document) when the corresponding terminology is available, otherwise they are unpacked as aem.AEType and aem.AEEnum respectively.

Unit types

Unit type values are represented by instances of the mactypes.Units class, e.g. mactypes.Units(3.0, 'inches'). See the mactypes manual for more information.

Miscellaneous types

The Apple Event Manager defines many other AE types whose names and codes are defined by appscript for completeness. A few of these types are of occasional interest to users, the rest can simply be ignored. In most cases, values of these types will be represented by raw aem.ae.AEDesc instances as appscript doesn't automatically convert them to native objects.