1 2 :mod:`aetools` --- OSA client support 3 ===================================== 4 5 .. module:: aetools 6 :platform: Mac 7 :synopsis: Basic support for sending Apple Events 8 :deprecated: 9 .. sectionauthor:: Jack Jansen <Jack.Jansen (a] cwi.nl> 10 .. moduleauthor:: Jack Jansen 11 12 The :mod:`aetools` module contains the basic functionality on which Python 13 AppleScript client support is built. It also imports and re-exports the core 14 functionality of the :mod:`aetypes` and :mod:`aepack` modules. The stub packages 15 generated by :mod:`gensuitemodule` import the relevant portions of 16 :mod:`aetools`, so usually you do not need to import it yourself. The exception 17 to this is when you cannot use a generated suite package and need lower-level 18 access to scripting. 19 20 The :mod:`aetools` module itself uses the AppleEvent support provided by the 21 :mod:`Carbon.AE` module. This has one drawback: you need access to the window 22 manager, see section :ref:`osx-gui-scripts` for details. This restriction may be 23 lifted in future releases. 24 25 .. note:: 26 27 This module has been removed in Python 3.x. 28 29 30 The :mod:`aetools` module defines the following functions: 31 32 33 .. function:: packevent(ae, parameters, attributes) 34 35 Stores parameters and attributes in a pre-created ``Carbon.AE.AEDesc`` object. 36 ``parameters`` and ``attributes`` are dictionaries mapping 4-character OSA 37 parameter keys to Python objects. The objects are packed using 38 ``aepack.pack()``. 39 40 41 .. function:: unpackevent(ae[, formodulename]) 42 43 Recursively unpacks a ``Carbon.AE.AEDesc`` event to Python objects. The function 44 returns the parameter dictionary and the attribute dictionary. The 45 ``formodulename`` argument is used by generated stub packages to control where 46 AppleScript classes are looked up. 47 48 49 .. function:: keysubst(arguments, keydict) 50 51 Converts a Python keyword argument dictionary ``arguments`` to the format 52 required by ``packevent`` by replacing the keys, which are Python identifiers, 53 by the four-character OSA keys according to the mapping specified in 54 ``keydict``. Used by the generated suite packages. 55 56 57 .. function:: enumsubst(arguments, key, edict) 58 59 If the ``arguments`` dictionary contains an entry for ``key`` convert the value 60 for that entry according to dictionary ``edict``. This converts human-readable 61 Python enumeration names to the OSA 4-character codes. Used by the generated 62 suite packages. 63 64 The :mod:`aetools` module defines the following class: 65 66 67 .. class:: TalkTo([signature=None, start=0, timeout=0]) 68 69 Base class for the proxy used to talk to an application. ``signature`` overrides 70 the class attribute ``_signature`` (which is usually set by subclasses) and is 71 the 4-char creator code defining the application to talk to. ``start`` can be 72 set to true to enable running the application on class instantiation. 73 ``timeout`` can be specified to change the default timeout used while waiting 74 for an AppleEvent reply. 75 76 77 .. method:: TalkTo._start() 78 79 Test whether the application is running, and attempt to start it if not. 80 81 82 .. method:: TalkTo.send(code, subcode[, parameters, attributes]) 83 84 Create the AppleEvent ``Carbon.AE.AEDesc`` for the verb with the OSA designation 85 ``code, subcode`` (which are the usual 4-character strings), pack the 86 ``parameters`` and ``attributes`` into it, send it to the target application, 87 wait for the reply, unpack the reply with ``unpackevent`` and return the reply 88 appleevent, the unpacked return values as a dictionary and the return 89 attributes. 90 91
