py-aem manual | 6. Building and sending events

#

## 6. Building and sending events

### The `Application` class's `event` method

The `Application` class's `event` method is used to create new Apple events targetted at the specified application.

            event(self, event, params={}, atts={}, returnid=kae.kAEAutoGenerateReturnID,
                    codecs=None) -- construct an Apple event
                event : bytes -- 8-letter code indicating event's class and id,
                        e.g. b'coregetd'
                params : dict -- a dict of form {AE_code:anything,...} containing zero
                        or more event parameters (message arguments)
                atts : dict -- a dict of form {AE_code:anything,...} containing zero
                        or more event attributes (event info)
                returnid : int  -- reply event's ID
                codecs : Codecs | None -- custom codecs to use when packing/unpacking
                        this event; if None, codecs supplied in Application.__init__
                        are used
                Result : Event -- a ready-to-send Apple event

### The `Event` class

The `Event` class represents an Apple event that has been packed and is ready to send.

    Event

        Methods:

            send(self, timeout=kae.kAEDefaultTimeout, flags=kae.kAEWaitReply) -- send event
                timeout : int | kae.kAEDefaultTimeout | kae.kAENoTimeout -- no. of ticks
                        to wait for application reply before raising timeout error
                flags : int -- bitwise flags determining how event should be handled
                Result : anything -- value returned by application, if any

### Constants

The following constants are defined in `aem.kae`.

#### Common parameter keys

    keyDirectObject
    keyAERequestedType

(The value for a `keyAERequestedType` parameter should be an `AEType` instance.)

Other parameter keys are defined by individual applications.

#### Attribute keys

Most of the following attributes are already supplied by other means (e.g. `keyEventClassAttr`, `keyEventIDAttr` are supplied separately when creating an Apple event; `keyTimeoutAttr` when sending it) and are only of interest if unpacking AppleEvent descriptors manually. A few may be used when passing an attributes dict to `Application.event` (`enumConsiderations`, `enumConsidsAndIgnores`, `keySubjectAttr`):

    keyTransactionIDAttr
    keyReturnIDAttr
    keyEventClassAttr
    keyEventIDAttr
    keyAddressAttr
    keyOptionalKeywordAttr
    keyTimeoutAttr
    keyInteractLevelAttr
    keyEventSourceAttr
    keyOriginalAddressAttr
    keyAcceptTimeoutAttr
    enumConsiderations
    enumConsidsAndIgnores
    keySubjectAttr

The value of the `enumConsiderations` attribute should be a list containing zero or more `AEEnum` instances with the following codes:

    kAECase
    kAEDiacritic
    kAEWhiteSpace
    kAEHyphens
    kAEExpansion
    kAEPunctuation
    kASConsiderReplies
    kASNumericStrings

See the Mac OS X Apple Event Manager documentation for more info. Note that the `enumConsiderations` attribute is deprecated in favour of the `enumConsidsAndIgnores` attribute.

The value of the `enumConsidsAndIgnores` attribute should be an integer composed from the sum of zero or more of the following bit masks:

    kAECaseConsiderMask
    kAEDiacriticConsiderMask
    kAEWhiteSpaceConsiderMask
    kAEHyphensConsiderMask
    kAEExpansionConsiderMask
    kAEPunctuationConsiderMask
    kASConsiderRepliesConsiderMask
    kASNumericStringsConsiderMask

    kAECaseIgnoreMask
    kAEDiacriticIgnoreMask
    kAEWhiteSpaceIgnoreMask
    kAEHyphensIgnoreMask
    kAEExpansionIgnoreMask
    kAEPunctuationIgnoreMask
    kASConsiderRepliesIgnoreMask
    kASNumericStringsIgnoreMask

#### Send flag constants

The value of the `send` method's `flags` argument should be an integer composed from the sum of zero or more of the following bit masks:

    kAENoReply
    kAEQueueReply
    kAEWaitReply

    kAEDontReconnect

    kAEWantReceipt

    kAENeverInteract
    kAECanInteract
    kAEAlwaysInteract

    kAECanSwitchLayer

See the Mac OS X Apple Event Manager documentation for details.

#### Other constants

    kAutoGenerateReturnID

### Exception classes

#### `aem.EventError`

The `aem.EventError` exception is raised by `Event.send` and represents an error raised by the target application or Apple Event Manager when sending an event.

    EventError(aem.ae.MacOSError)

        Properties:
            errornumber : int -- Mac OS error number
            errormessage : str -- application-supplied/generic error description
            offendingobject : anything | None -- object that caused the error,
                                                 if given by application
            expectedtype : anything | None -- object that caused a coercion error,
                                              if given by application
            partialresult : anything | None -- part of return value constructed
                                               before error occurred, if given
                                               by application

        Methods:

            __int__(self) -- Mac OS error number

            __str__(self) -- formatted description of error

#### `aem.ae.MacOSError`

The `aem.ae.MacOSError` exception is raised by the low-level `aem.ae` extension and represents an error raised by the Apple Event Manager. The `aem` API usually traps these low-level errors and throws more descriptive errors in their place (e.g. `aem.EventError`).

    MacOSError(Exception)

        Attributes:
            args : list -- contains a single integer, the Mac OS error number