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 type | appscript name | Python type |
|---|---|---|
typeNull | k.null | types.NoneType |
typeBoolean | k.boolean | bool |
typeInteger | k.integer | int |
typeFloat | k.float | float |
typeChar * | k.string | str |
typeStyledText * | k.styled_text | str |
typeIntlText * | k.international_text | str |
typeUnicodeText | k.unicode_text | str |
typeAEList | k.list | list |
typeAERecord | k.record | dict |
typeLongDateTime | k.date | datetime.datetime |
typeAlias | k.alias | mactypes.Alias |
typeFileURL | k.file_url | mactypes.File |
typeFSRef | k.file_ref | mactypes.File |
typeFSS * | k.file_specification | mactypes.File |
typeData | k.data | bytes |
typeObjectSpecifier | k.reference | appscript reference |
typeInsertionLoc | k.location_reference | appscript insertion reference |
typeType | k.type_class | appscript keyword |
typeEnumerated | k.enumerator | appscript keyword |
unit types; e.g. typeFeet | unit 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.
