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.