mirror of
https://github.com/python/cpython.git
synced 2025-10-30 21:21:22 +00:00
358 lines
No EOL
14 KiB
HTML
358 lines
No EOL
14 KiB
HTML
<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
|
|
<html><head><title>Using the Open Scripting Architecture from Python</title></head>
|
|
<body>
|
|
<h1>Using the Open Scripting Architecture from Python</h1>
|
|
<hr>
|
|
|
|
<p>OSA support in Python is still not 100% complete, but
|
|
there is already enough in place to allow you to do some nifty things
|
|
with other programs from your python program. </p>
|
|
|
|
|
|
<p>
|
|
In this example, we will look at a scriptable application, extract its
|
|
“AppleScript Dictionary,” generate a Python interface package from
|
|
the dictionary, and use that package to control the application.
|
|
The application we are going to script is Disk Copy, Apple's standard
|
|
utility for making copies of floppies, creating files that are mountable
|
|
as disk images, etc.
|
|
Because we want
|
|
to concentrate on the OSA details, we won’t bother with a real
|
|
user-interface for our application. </p>
|
|
|
|
|
|
<p>
|
|
<em>When we say “AppleScript” in this document we actually mean
|
|
“the Open Scripting Architecture.” There is nothing
|
|
AppleScript-specific in the Python implementation. Most of this document
|
|
focuses on the classic Mac OS; <a href="#osx">Mac OS X</a> users have some
|
|
additional tools.</em>
|
|
</p>
|
|
|
|
<h2>Python OSA architecture</h2>
|
|
|
|
<p>Open Scripting suites and inheritance can be modelled rather nicely
|
|
with Python packages, so we generate
|
|
a package for each application we want to script. Each suite defined in
|
|
the application becomes a module in the
|
|
package, and the package main module imports everything from all the
|
|
submodules and glues together all the classes (in Python terminology—
|
|
events in OSA terminology or verbs in AppleScript terminology). </p>
|
|
|
|
<p>
|
|
A suite in an OSA application can extend the functionality of a standard
|
|
suite. This is implemented in Python by importing everything from the
|
|
module that implements the standard suites and overriding anything that has
|
|
been extended. The standard suites live in the StdSuite package. </p>
|
|
|
|
<p>
|
|
This all sounds complicated, but the good news is that basic
|
|
scripting is actually pretty simple. You can do strange and wondrous things
|
|
with OSA scripting once you fully understand it. </p>
|
|
|
|
<h2>Creating the Python interface package</h2>
|
|
|
|
|
|
<p>There is a tool in the standard distribution that can automatically
|
|
generate the interface packages. This tool is called
|
|
<code>gensuitemodule.py</code>, and lives in <code>Mac:scripts</code>.
|
|
It looks through a file
|
|
for an ‘AETE’ or ‘AEUT’ resource,
|
|
the internal representation of the
|
|
AppleScript dictionary, and parses the resource to generate the suite
|
|
modules.
|
|
When we start <code>gensuitemodule</code>, it asks us for an input file;
|
|
for our example,
|
|
we point it to the Disk Copy executable. </p>
|
|
|
|
<p>
|
|
Next, <code>gensuitemodule</code> wants a folder where it will store the
|
|
package it is going to generate.
|
|
Note that this is the package folder, not the parent folder, so we
|
|
navigate to <code>Python:Mac:Demo:applescript</code>, create a folder
|
|
<code>Disk_Copy</code>, and select that. </p>
|
|
|
|
<p>
|
|
We next specify the folder from which <code>gensuitemodule</code>
|
|
should import the standard suites. Here,
|
|
we always select <code>Python:Mac:Lib:lib-scriptpackages:StdSuites</code>. (There is
|
|
one exception to this rule: when you are generating <code>StdSuites</code> itself
|
|
you select <code>_builtinSuites</code>.)
|
|
</p>
|
|
|
|
<p>
|
|
It starts parsing the AETE resource, and for
|
|
each AppleEvent suite it finds, <code>gensuitemodule.py</code>
|
|
prompts us for the filename of the
|
|
resulting python module. Remember to change folders for the first
|
|
module—you don't want to clutter up, say, the
|
|
Disk Copy folder
|
|
with your python
|
|
interfaces. If you want to skip a suite, press <code>cancel</code> and the process
|
|
continues with the next suite. </p>
|
|
|
|
<h3>Summary</h3>
|
|
|
|
<ol>
|
|
|
|
<li>Run <code>gensuitemodule</code>.</li>
|
|
|
|
<li>Select the application (or OSAX) for which you would like a Python interface.</li>
|
|
|
|
<li>Select the package folder where the interface modules should be
|
|
stored.</li>
|
|
|
|
<li>Specify the folder <code>Python:Mac:Lib:lib-scriptpackages:StdSuites</code>
|
|
to import the standard suites (or <code>_builtinSuites</code> if you are
|
|
generating <code>StdSuites</code> itself). </li>
|
|
|
|
<li>Save the generated suites (use <code>cancel</code> to skip a suite).</li>
|
|
|
|
|
|
</ol>
|
|
|
|
|
|
<h3>Notes</h3>
|
|
|
|
|
|
<ul>
|
|
|
|
<li>The interface package may occasionally need some editing by hand. For example,
|
|
<code>gensuitemodule</code> does not handle all Python reserved words, so
|
|
if
|
|
one of the AppleScript verbs is a Python reserved word, a <code>SyntaxError</code>
|
|
may be raised when the package is imported.
|
|
Simply rename the class into something acceptable, if this happens;
|
|
take a look at how the
|
|
<code>print</code> verb is handled (automatically by <code>gensuitemodule</code>)
|
|
in the standard suites. But: f you need to edit your package this should be considered a
|
|
bug in gensuitemodule, so please report it so it can be fixed in future releases.
|
|
</li>
|
|
|
|
|
|
<li>If you want to re-create the StdSuite modules,
|
|
you should look in one of two places. With versions of AppleScript older than 1.4.0
|
|
(which first shipped with OS 9.0), you will find the
|
|
AEUT resources in <code>System Folder:Extensions:Scripting
|
|
Additions:Dialects:English Dialect</code>. For newer versions, you will
|
|
find them in <code>System Folder:Extensions:Applescript</code>.
|
|
</li>
|
|
|
|
<li>Since MacPython 2.0, this new structure, with packages
|
|
per application and submodules per suite, is used. Older MacPythons had a
|
|
single level of modules, with uncertain semantics. With the new structure,
|
|
it is possible for programs to override standard suites, as programs often do.
|
|
|
|
</li>
|
|
|
|
<li><code>Gensuitemodule.py</code> may ask you questions
|
|
like “Where is enum 'xyz ' declared?”.
|
|
This is either due to a misunderstanding on my part or (rather too commonly)
|
|
bugs in the AETE resources. Pressing <code>cancel</code> is usually the
|
|
right choice: it will cause the specific enum not to be treated as an enum
|
|
but as a “normal” type. As things like fsspecs and TEXT strings clearly are
|
|
not enumerators, this is correct. If someone understands what is really going on
|
|
here, please let me know.</li>
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
<h2>The Python interface package contents</h2>
|
|
|
|
<p>
|
|
Let’s glance at the
|
|
<a href="applescript/Disk_Copy">Disk_Copy</a> package just created. You
|
|
may want to open Script Editor alongside to see how it
|
|
interprets the dictionary.
|
|
</p>
|
|
|
|
|
|
<p>
|
|
The main package module is in <code>__init__.py</code>.
|
|
The only interesting bit is the <code>Disk_Copy</code> class, which
|
|
includes the event handling classes from the individual suites. It also
|
|
inherits <code>aetools.TalkTo</code>, which is a base class that handles all
|
|
details on how to start the program and talk to it, and a class variable
|
|
<code>_signature</code> which is the default application this class will talk
|
|
to (you can override this in various ways when you instantiate your class, see
|
|
<code>aetools.py</code> for details).
|
|
</p>
|
|
|
|
<p>
|
|
The <a href="applescript/Disk_Copy/Special_Events.py">Special_Events</a>
|
|
module is a nice example of a suite module.
|
|
The <code>Special_Events_Events</code> class is the bulk of the code
|
|
generated. For each verb, it contains a method. Each method knows what
|
|
arguments the verb expects, and it makes use of keyword
|
|
arguments to present a palatable
|
|
interface to the python programmer.
|
|
|
|
Notice that each method
|
|
calls some routines from <code>aetools</code>, an auxiliary module
|
|
living in <code>Mac:Lib</code>.
|
|
The other thing to notice is that each method calls
|
|
<code>self.send</code>. This comes from the <code>aetools.TalkTo</code>
|
|
baseclass. </p>
|
|
|
|
|
|
<p>
|
|
After the big class, there are a number of little class declarations. These
|
|
declarations are for the (AppleEvent) classes and properties in the suite.
|
|
They allow you to create object IDs, which can then be passed to the verbs.
|
|
For instance,
|
|
when scripting the popular email program Eudora,
|
|
you would use <code>mailbox("inbox").message(1).sender</code>
|
|
to get the name of the sender of the first message in mailbox
|
|
inbox. It is
|
|
also possible to specify this as <code>sender(message(1, mailbox("inbox")))</code>,
|
|
which is sometimes needed because these classes don’t always inherit correctly
|
|
from baseclasses, so you may have to use a class or property from another
|
|
suite. </p>
|
|
|
|
<p>
|
|
Next we get the enumeration dictionaries, which allow you to pass
|
|
english names as arguments to verbs, so you don't have to bother with the 4-letter
|
|
type code. So, you can say
|
|
<code>
|
|
diskcopy.create(..., filesystem="Mac OS Standard")
|
|
</code>
|
|
as it is called in Script Editor, instead of the cryptic lowlevel
|
|
<code>
|
|
diskcopy.create(..., filesystem="Fhfs")
|
|
</code></p>
|
|
|
|
<p>
|
|
Finally, we get the “table of contents” of the module, listing all
|
|
classes and such
|
|
by code, which is used by <code>gensuitemodule</code> itself: if you use this
|
|
suite as a base package in a later run this is how it knows what is defined in this
|
|
suite, and what the Python names are.
|
|
</p>
|
|
|
|
<h3>Notes</h3>
|
|
|
|
<ul>
|
|
|
|
<li>The <code>aetools</code> module contains some other nifty
|
|
AppleEvent tools as well. Have a look at it sometime, there is (of
|
|
course) no documentation yet.
|
|
</li>
|
|
|
|
<li>There are also some older object specifiers for standard objects in aetools.
|
|
You use these in the form <code>aetools.Word(10,
|
|
aetools.Document(1))</code>, where the corresponding AppleScript
|
|
terminology would be <code>word 10 of the first
|
|
document</code>. Examine
|
|
<code>aetools</code> and <code>aetools.TalkTo</code>
|
|
along with
|
|
the comments at the end of your suite module if you need to create
|
|
more than the standard object specifiers.
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h2>Using a Python suite module</h2>
|
|
|
|
<p>
|
|
Now that we have created the suite module, we can use it in a Python script.
|
|
In older MacPython distributions this used to be a rather
|
|
complicated affair, but with the package scheme and with the application signature
|
|
known by the package it is very simple: you import the package and instantiate
|
|
the class, e.g.
|
|
<code>
|
|
talker = Disk_Copy.Disk_Copy(start=1)
|
|
</code>
|
|
You will usually specify the <code>start=1</code>: it will run the application if it is
|
|
not already running.
|
|
You may want to omit it if you want to talk to the application
|
|
only if it is already running, or if the application is something like the Finder.
|
|
Another way to ensure that the application is running is to call <code>talker._start()</code>.
|
|
</p>
|
|
|
|
<p>
|
|
Looking at the sourcefile <a
|
|
href="applescript/makedisk.py">makedisk.py</a>, we see that it starts
|
|
with some imports. Naturally, one of these is the Python interface to Disk
|
|
Copy.</p>
|
|
|
|
<p>
|
|
The main program itself is a wonder of simplicity: we create the
|
|
object (<code>talker</code>) that talks to Disk Copy,
|
|
create a disk, and mount it. The bulk of
|
|
the work is done by <code>talker</code> and the Python interface package we
|
|
just created.</p>
|
|
|
|
<p>
|
|
The exception handling does warrant a few comments, though. Since
|
|
AppleScript is basically a connectionless RPC protocol,
|
|
nothing happens
|
|
when we create the <code>talker</code> object. Hence, if the destination application
|
|
is not running, we will not notice until we send our first
|
|
command (avoid this as described above). There is another thing to note about errors returned by
|
|
AppleScript calls: <code>MacOS.Error</code> is raised for
|
|
all of the errors that are known to be <code>OSErr</code>-type errors,
|
|
while
|
|
server generated errors raise <code>aetools.Error</code>. </p>
|
|
|
|
<h2>Scripting Additions</h2>
|
|
|
|
<p>
|
|
If you want to use any of the scripting additions (or OSAXen, in
|
|
everyday speech) from a Python program, you can use the same method
|
|
as for applications, i.e. run <code>gensuitemodule</code> on the
|
|
OSAX (commonly found in <code>System Folder:Scripting Additions</code>
|
|
or something similar). There is one minor gotcha: the application
|
|
signature to use is <code>MACS</code>. You will need to edit the main class
|
|
in the <code>__init__.py</code> file of the created package and change the value
|
|
of <code>_signature</code> to <code>MACS</code>, or use a subclass to the
|
|
same effect.
|
|
</p>
|
|
|
|
<p>
|
|
There are two minor points to watch out for when using <code>gensuitemodule</code>
|
|
on OSAXen: they appear all to define the class <code>System_Object_Suite</code>,
|
|
and a lot of them have the command set in multiple dialects. You have to
|
|
watch out for name conflicts and make sure you select a reasonable dialect
|
|
(some of the non-English dialects cause <code>gensuitemodule</code> to generate incorrect
|
|
Python code). </p>
|
|
|
|
Despite these difficulties, OSAXen offer a lot of possibilities. Take a
|
|
look at some of the OSAXen in the Scripting Additions folder, or
|
|
<A HREF="http://www.osaxen.com/index.php">download</A> some from the net.
|
|
|
|
<h2>Further Reading</h2>
|
|
|
|
<p>
|
|
If you want to look at more involved examples of applescripting, look at the standard
|
|
modules <code>findertools</code> and <code>nsremote</code>, or (possibly better, as it
|
|
is more involved) <code>fullbuild</code> from the <code>Mac:scripts</code> folder.
|
|
</p>
|
|
|
|
<h2><a name="alternatives">Alternatives</a></h2>
|
|
|
|
<h3><a name="osx">Mac OS X</a></h3>
|
|
|
|
<p>
|
|
Under Mac OS X, the above still works, but with some new difficulties.
|
|
The application package structure can hide the ‘AETE’ or
|
|
‘AEUT’ resource from <code>gensuitemodule</code>, so that,
|
|
for example, it cannot generate an OSA interface to iTunes. Script
|
|
Editor gets at the dictionary of such programs using a ‘Get
|
|
AETE’ AppleEvent, if someone wants to donate code to use the same
|
|
method for gensuitemodule: by all means!
|
|
</p>
|
|
|
|
<p>
|
|
One alternative is available through the Unix command line version of python.
|
|
Apple has provided the <code>osacompile</code> and <code>osascript</code> tools,
|
|
which can be used to compile and execute scripts written in OSA languages. See the
|
|
man pages for more details.
|
|
</p>
|
|
|
|
|
|
</body>
|
|
</html> |