1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
|
:mod:`aetools` --- OSA client support
=====================================
.. module:: aetools
:platform: Mac
:synopsis: Basic support for sending Apple Events
.. 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:
.. 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.
|
