
``aetools`` --- OSA client support
**********************************

*Platforms: *Mac

The ``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 ``aetypes`` and ``aepack``
modules. The stub packages generated by ``gensuitemodule`` import the
relevant portions of ``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 ``aetools`` module itself uses the AppleEvent support provided by
the ``Carbon.AE`` module. This has one drawback: you need access to
the window manager, see section *Running scripts with a GUI* for
details. This restriction may be lifted in future releases.

Note: This module has been removed in Python 3.x.

The ``aetools`` module defines the following functions:

aetools.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()``.

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

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

aetools.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 ``aetools`` module defines the following class:

class class aetools.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.

TalkTo._start()

   Test whether the application is running, and attempt to start it if
   not.

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.
