py-appscript manual | 6. Classes and enumerated types

#

## 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.