mirror of https://github.com/python/cpython.git
208 lines
10 KiB
HTML
208 lines
10 KiB
HTML
<HTML><HEAD><TITLE>Using Open Scripting Extension from Python</TITLE></HEAD>
|
|
<BODY>
|
|
<H1>Using Open Scripting Extension from Python</H1>
|
|
<HR>
|
|
|
|
OSA support in Python is still not 100% complete, but
|
|
there is already enough in place to allow you to do some nifty things
|
|
to other programs from your python program. <P>
|
|
|
|
<CITE>
|
|
Actually, when we say "AppleScript" in this document we actually mean
|
|
"the Open Scripting Architecture", there is nothing
|
|
AppleScript-specific in the Python implementation. <p>
|
|
</CITE>
|
|
|
|
In this example, we will look at a scriptable application, extract its
|
|
"AppleScript Dictionary" and generate a Python interface module from
|
|
that and use that module to control the application. Because we want
|
|
to concentrate on the OSA details we don't bother with a real
|
|
user-interface for our application. <p>
|
|
|
|
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. <p>
|
|
|
|
<H2>Python OSA architecture</H2>
|
|
|
|
Open Scripting suites and inheritance can be modelled rather nicely with
|
|
with Python packages, so for each application we want to script we generate
|
|
a package. 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 all the classes (Python terminology, OSA terminology is
|
|
events, AppleScript terminology is verbs) together. <p>
|
|
|
|
A suite in an OSA application can extend the functionality of a standard
|
|
suite, and this is implemented in Python by importing everything from the
|
|
module that implements the standard suite and overriding anything that has
|
|
been extended. The standard suites live in the StdSuite package. <p>
|
|
|
|
This all sounds complicated, and you can do strange and wondrous things
|
|
with it once you fully understand it, but the good news is that simple
|
|
scripting is actually pretty simple. <p>
|
|
|
|
<H2>Creating the Python interface module</H2>
|
|
|
|
There is a tool in the standard distribution that looks through a file
|
|
for an 'AETE' or 'AEUT' resource, the internal representation of the
|
|
AppleScript dictionary. This tool is called
|
|
<CODE>gensuitemodule.py</CODE>, and lives in <CODE>Mac:scripts</CODE>.
|
|
When we start it, it asks us for an input file and we point it to the
|
|
Disk Copy executable. <p>
|
|
|
|
Next it 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>
|
|
|
|
Next it wants the folder from which it should import the standard suites. Here
|
|
you always select <code>Python:Mac:Lib:lib-scriptpackages</code>. (There is
|
|
one exception to this rule: when you are generating <code>StdSuites</code> itself
|
|
you select <code>cancel</code>, for obvious reasons). <p>
|
|
|
|
It starts parsing the AETE resource, and for
|
|
each AppleEvent suite it finds it 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 the Eudora folder with your python
|
|
interfaces. If you want to skip a suite you press cancel and the process
|
|
continues with the next suite. <p>
|
|
|
|
Gensuitemodule may ask you questions like "Where is enum 'xyz ' declared?".
|
|
This is either due to a misunderstanding on my part or (rather too common)
|
|
bugs in the AETE resources. Pressing <code>cancel</code> is usually the
|
|
right option, 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. <p>
|
|
|
|
<BLOCKQUOTE>
|
|
Time for a sidebar. If you want to re-create the StdSuite modules
|
|
you should look in one of two places. On older systems you will find the
|
|
AEUT resources in <CODE>System Folder:Extensions:Scripting
|
|
Additions:Dialects:English Dialect</CODE>. On newer systems you will
|
|
find them in <code>System Folder:Extensions:Applescript</code>. <p>
|
|
</BLOCKQUOTE>
|
|
|
|
Let's glance at the <A
|
|
HREF="applescript/Disk_Copy">Disk_Copy</A> package just created. You
|
|
may want to open Script Editor alongside, and have a look at how it
|
|
interprets the dictionary. The main package module is in <code>__init__.py</code>
|
|
and 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 when you instantiate your class, see
|
|
<code>aetools.py</code> for details).
|
|
<p>
|
|
<blockquote>
|
|
Let us do another sidebar. 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.
|
|
It is a good idea to convert your own old programs to the new scheme, but if you
|
|
really want the old standard suites are still available in
|
|
<code>:Mac:Lib:lib-scripting</code>.
|
|
</blockquote>
|
|
|
|
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 handy use of keyword
|
|
arguments to present a palatable
|
|
interface to the python programmer. You will see that each method
|
|
calls some routines from <CODE>aetools</CODE>, an auxiliary module
|
|
living in <CODE>Lib:toolbox</CODE> which contains some other nifty
|
|
AppleEvent tools as well. Have a look at it sometime, there is (of
|
|
course) no documentation yet. <p>
|
|
|
|
The other thing you notice is that each method calls
|
|
<CODE>self.send</CODE>, this comes from the <code>aetools.TalkTo</code> baseclass. <p>
|
|
|
|
After the big class we get 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, to get the name of the sender of the first message in mailbox
|
|
inbox you would use <code>mailbox("inbox").message(1).sender</code>. 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>
|
|
|
|
<blockquote>
|
|
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 the two modules mentioned above along with
|
|
the comments at the end of your suite module if you need to create
|
|
more than the standard object specifiers.
|
|
</blockquote>
|
|
|
|
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><PRE>
|
|
diskcopy.create(..., filesystem="Mac OS Standard")
|
|
</PRE></CODE>
|
|
as it is called in Script Editor, in stead of the cryptic lowlevel
|
|
<CODE><PRE>
|
|
diskcopy.create(..., filesystem="Fhfs")
|
|
</PRE></CODE><p>
|
|
|
|
Finally, we get the "table of contents" of the module, listing all classes and such
|
|
by code, which is used by gensuitemodule. <p>
|
|
|
|
<H2>Using a Python suite module</H2>
|
|
|
|
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, as
|
|
<CODE><PRE>
|
|
talker = Disk_Copy.Disk_Copy(start=1)
|
|
</PRE></CODE>
|
|
You will usually specify the start=1: 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. <p>
|
|
|
|
Looking at the sourcefile <A
|
|
HREF="applescript/makedisk.py">makedisk.py</A> we see that it starts
|
|
with some imports.
|
|
|
|
The main program itself is a wonder of simplicity. We create the
|
|
object that talks to Disk Copy, creates a disk and mounts it. <p>
|
|
|
|
The exception handling does need a few comments, though. Since
|
|
AppleScript is basically a connectionless RPC protocol nothing happens
|
|
when we create to talker object. Hence, if the destination application
|
|
is not running we will not notice until we send our first
|
|
command. 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,
|
|
server generated errors raise <CODE>aetools.Error</CODE>. <p>
|
|
|
|
<H2>Scripting Additions</H2>
|
|
|
|
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:Extensions:Scripting Additions</CODE>
|
|
or something similar). There is one minor gotcha: the application
|
|
signature to use is <CODE>'MACS'</CODE>. <P>
|
|
|
|
There are two minor points to watch out for when using gensuitemodule
|
|
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, so, and make sure you select a reasonable dialect
|
|
(some of the non-english dialects cause gensuitemodule to generate incorrect
|
|
Python code). <P>
|
|
|
|
<H2>Further Reading</H2>
|
|
|
|
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 Mac:scripts folder.
|