Edit File: aetools.txt
:mod:`aetools` --- OSA client support ===================================== .. module:: aetools :platform: Mac :synopsis: Basic support for sending Apple Events :deprecated: .. sectionauthor:: Jack Jansen <Jack.Jansen@cwi.nl> .. moduleauthor:: Jack Jansen The :mod:`aetools` module contains the basic functionality on which Python AppleScript client support is built. It also imports and re-exports the core functionality of the :mod:`aetypes` and :mod:`aepack` modules. The stub packages generated by :mod:`gensuitemodule` import the relevant portions of :mod:`aetools`, so usually you do not need to import it yourself. The exception to this is when you cannot use a generated suite package and need lower-level access to scripting. The :mod:`aetools` module itself uses the AppleEvent support provided by the :mod:`Carbon.AE` module. This has one drawback: you need access to the window manager, see section :ref:`osx-gui-scripts` for details. This restriction may be lifted in future releases. .. note:: This module has been removed in Python 3.x. The :mod:`aetools` module defines the following functions: .. function:: packevent(ae, parameters, attributes) Stores parameters and attributes in a pre-created ``Carbon.AE.AEDesc`` object. ``parameters`` and ``attributes`` are dictionaries mapping 4-character OSA parameter keys to Python objects. The objects are packed using ``aepack.pack()``. .. function:: unpackevent(ae[, formodulename]) Recursively unpacks a ``Carbon.AE.AEDesc`` event to Python objects. The function returns the parameter dictionary and the attribute dictionary. The ``formodulename`` argument is used by generated stub packages to control where AppleScript classes are looked up. .. function:: keysubst(arguments, keydict) Converts a Python keyword argument dictionary ``arguments`` to the format required by ``packevent`` by replacing the keys, which are Python identifiers, by the four-character OSA keys according to the mapping specified in ``keydict``. Used by the generated suite packages. .. function:: enumsubst(arguments, key, edict) If the ``arguments`` dictionary contains an entry for ``key`` convert the value for that entry according to dictionary ``edict``. This converts human-readable Python enumeration names to the OSA 4-character codes. Used by the generated suite packages. The :mod:`aetools` module defines the following class: .. class:: TalkTo([signature=None, start=0, timeout=0]) Base class for the proxy used to talk to an application. ``signature`` overrides the class attribute ``_signature`` (which is usually set by subclasses) and is the 4-char creator code defining the application to talk to. ``start`` can be set to true to enable running the application on class instantiation. ``timeout`` can be specified to change the default timeout used while waiting for an AppleEvent reply. .. method:: TalkTo._start() Test whether the application is running, and attempt to start it if not. .. method:: TalkTo.send(code, subcode[, parameters, attributes]) Create the AppleEvent ``Carbon.AE.AEDesc`` for the verb with the OSA designation ``code, subcode`` (which are the usual 4-character strings), pack the ``parameters`` and ``attributes`` into it, send it to the target application, wait for the reply, unpack the reply with ``unpackevent`` and return the reply appleevent, the unpacked return values as a dictionary and the return attributes.