Mac/Demo/applescript.html - platform/external/python/cpython2 - Gitiles

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