py-appscript

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