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

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:

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.