Blame - Mac/Demo/applescript.html - platform/external/python/cpython3

blob: 7db5ba6020b2dd222a272869ded7b4c419661e77 [file] [log] [blame]

Jack Jansen	a630813	1996-03-18 13:38:52 +0000	[diff] [blame]	1	<HTML><HEAD><TITLE>Using Open Scripting Extension from Python</TITLE></HEAD>
				2	<BODY>
				3	<H1>Using Open Scripting Extension from Python</H1>
				4	<HR>
				5
				6	OSA support in Python is still far from complete, and what
				7	support there is is likely to change in the forseeable future. Still,
				8	there is already enough in place to allow you to do some nifty things
				9	to other programs from your python program. <P>
				10
				11	<CITE>
				12	Actually, when we say "AppleScript" in this document we actually mean
				13	"the Open Scripting Architecture", there is nothing
				14	AppleScript-specific in the Python implementation. <p>
				15	</CITE>
				16
				17	In this example, we will look at a scriptable application, extract its
				18	"AppleScript Dictionary" and generate a Python interface module from
				19	that and use that module to control the application. Because we want
				20	to concentrate on the OSA details we don't bother with a real
				21	user-interface for our application. <p>
				22
				23	The application we are going to script is Eudora Light, a free mail
				24	program from <A HREF="http://www.qualcomm.com">QualComm</A>. This is a
				25	very versatile mail-reader, and QualComm has an accompanying
				26	commercial version once your needs outgrow Eudora Light. Our program
				27	will tell Eudora to send queued mail, retrieve mail or quit. <p>
				28
				29	<H2>Creating the Python interface module</H2>
				30
				31	There is a tool in the standard distribution that looks through a file
				32	for an 'AETE' or 'AEUT' resource, the internal representation of the
				33	AppleScript dictionary. This tool is called
				34	<CODE>gensuitemodule.py</CODE>, and lives in
Jack Jansen	0836542	1996-04-19 15:56:08 +0000	[diff] [blame^]	35	<CODE>Mac:scripts</CODE>. When we start it, it asks us for an input
Jack Jansen	a630813	1996-03-18 13:38:52 +0000	[diff] [blame]	36	file and we point it to the Eudora Light executable. It starts parsing
				37	the AETE resource, and for each AppleEvent suite it finds it prompts
				38	us for the filename of the resulting python module. Remember to change
				39	folders for the first module, you don't want to clutter up the Eudora
				40	folder with your python interfaces. If you want to skip a suite you
				41	press cancel and the process continues with the next suite. In the
				42	case of Eudora, you do <EM>not</EM> want to generate the Required
				43	suite, because it will be empty. AppleScript understands that an empty
				44	suite means "incorporate the whole standard suite by this name",
				45	gensuitemodule does not currently understand this. Creating the empty
				46	<CODE>Required_Suite.py</CODE> would hide the correct module of that
				47	name from our application. <p>
				48
Jack Jansen	0836542	1996-04-19 15:56:08 +0000	[diff] [blame^]	49	<BLOCKQUOTE>
Jack Jansen	a630813	1996-03-18 13:38:52 +0000	[diff] [blame]	50	Time for a sidebar. If you want to re-create
				51	<CODE>Required_Suite.py</CODE> or one of the other standard modules
				52	you should look in <CODE>System Folder:Extensions:Scripting
				53	Additions:Dialects:English Dialect</CODE>, that is where the core
				54	AppleEvent dictionaries live. Also, if you are looking for the
				55	<CODE>Finder_Suite</CODE> interface: don't look in the finder (it has
				56	an old System 7.0 scripting suite), look at the extension <CODE>Finder
				57	Scripting Extension</CODE>. <p>
Jack Jansen	0836542	1996-04-19 15:56:08 +0000	[diff] [blame^]	58	</BLOCKQUOTE>
Jack Jansen	a630813	1996-03-18 13:38:52 +0000	[diff] [blame]	59
				60	Let's glance at the <A
				61	HREF="scripting/Eudora_Suite.py">Eudora_Suite.py</A> just created. You
				62	may want to open Script Editor alongside, and have a look at how it
				63	interprets the dictionary. EudoraSuite.py starts with some
				64	boilerplate, then come some dictionaries implementing the OSA
				65	Enumerations, then a big class definition with methods for each
				66	AppleScript Verb and finally some comments. The Enumerations we will
				67	skip, it suffices to know that whenever you have to pass an enumerator
				68	to a method you can pass the english name and don't have to bother
				69	with the 4-letter type code. So, you can say
				70	<CODE><PRE>
				71	eudora.notice(occurrence="mail_arrives")
				72	</PRE></CODE>
				73	instead of the rather more cryptic
				74	<CODE><PRE>
				75	eudora.notice(occurrence="wArv")
				76	</PRE></CODE>
				77
				78	The <CODE>Eudora_Suite</CODE> class is the bulk of the code
				79	generated. For each verb it contains a method. Each method knows what
				80	arguments the verb expects, and it makes handy use of the keyword
				81	argument scheme introduced in Python 1.3 to present a palatable
				82	interface to the python programmer. You will see that each method
				83	calls some routines from <CODE>aetools</CODE>, an auxiliary module
Jack Jansen	0836542	1996-04-19 15:56:08 +0000	[diff] [blame^]	84	living in <CODE>Lib:toolbox</CODE> which contains some other nifty
Jack Jansen	a630813	1996-03-18 13:38:52 +0000	[diff] [blame]	85	AppleEvent tools as well. Have a look at it sometime, there is (of
				86	course) no documentation yet. <p>
				87
				88	The other thing you notice is that each method calls
				89	<CODE>self.send</CODE>, but no such method is defined. You will have
				90	to provide it by subclassing or multiple inheritance, as we shall see
				91	later. <p>
				92
				93	The module ends with some comments. Sadly, gensuitemodule is not yet
				94	able to turn the Object Specifiers into reasonable Python code. For
				95	now, if you need object specifiers, you will have to use the routines
				96	defined in <CODE>aetools.py</CODE> (and <CODE>aetypes.py</CODE>, which
				97	it incorporates). You use these in the form <CODE>aetools.Word(10,
				98	aetools.Document(1))</CODE> where the corresponding AppleScript
				99	terminology would be <CODE>word 10 of the first
				100	document</CODE>. Examine the two modules mentioned above along with
				101	the comments at the end of your suite module if you need to create
				102	more than the standard object specifiers. <p>
				103
				104	<H2>Using a Python suite module</H2>
				105
				106	Now that we have created the suite module we can use it in an
				107	application. We do this by creating a class that inherits
				108	<CODE>Eudora_Suite</CODE> and the <CODE>TalkTo</CODE> class from
				109	<CODE>aetools</CODE>. The <CODE>TalkTo</CODE> class is basically a
				110	container for the <CODE>send</CODE> method used by the methods from
				111	the suite classes. <p>
				112
				113	Actually, our class will also inherit <CODE>Required_Suite</CODE>,
				114	because we also need functionality from that suite: the quit
				115	command. Gensuitemodule could have created this completely derived
				116	class for us, since it has access to all information needed to build
				117	the class but unfortunately it does not do so at the moment. All in
				118	all, the heart of our program looks like this:
				119	<CODE><PRE>
				120	import Eudora_Suite, Required_Suite, aetools
				121
				122	class Eudora(aetools.TalkTo, Required_Suite.Required_Suite, \
				123	Eudora_Suite.Eudora_Suite):
				124	pass
				125	</PRE></CODE>
				126
				127	Yes, our class body is <CODE>pass</CODE>, all functionality is already
				128	provided by the base classes, the only thing we have to do is glue it
				129	together in the right way. <p>
				130
				131	Looking at the sourcefile <A
				132	HREF="scripting/testeudora.py">testeudora.py</A> we see that it starts
Jack Jansen	0836542	1996-04-19 15:56:08 +0000	[diff] [blame^]	133	with some imports. Then we get the class definition
Jack Jansen	a630813	1996-03-18 13:38:52 +0000	[diff] [blame]	134	for our main object and a constant giving the signature of Eudora. <p>
				135
				136	This, again, needs a little explanation. There are various ways to
				137	describe to AppleScript which program we want to talk to, but the
				138	easiest one to use (from Python, at least) is creator
				139	signature. Application name would be much nicer, but Python currently
				140	does not have a module that interfaces to the Finder database (which
				141	would allow us to map names to signatures). The other alternative,
				142	<CODE>ChooseApplication</CODE> from the program-to-program toolbox, is
				143	also not available from Python at the moment. <p>
				144
				145	The main program itself is a wonder of simplicity. We create the
				146	object that talks to Eudora (passing the signature as argument), ask
				147	the user what she wants and call the appropriate method of the talker
				148	object. The use of keyword arguments with the same names as used by
				149	AppleScript make passing the parameters a breeze. <p>
				150
				151	The exception handling does need a few comments, though. Since
				152	AppleScript is basically a connectionless RPC protocol nothing happens
				153	when we create to talker object. Hence, if the destination application
				154	is not running we will not notice until we send our first
				155	command. There is another thing to note about errors returned by
				156	AppleScript calls: even though <CODE>MacOS.Error</CODE> is raised not
				157	all of the errors are actually <CODE>OSErr</CODE>-type errors, some
				158	are error codes returned by the server application. In that case, the
				159	error message will be incorrect. <p>
				160
				161	That concludes our simple example. Again, let me emphasize that
				162	scripting support in Python is not very complete at the moment, and
				163	the details of how to use AppleEvents will definitely change in the
				164	near future. This will not only fix all the ideosyncracies noted in
				165	this document but also break existing programs, since the current
				166	suite organization will have to change to fix some of the problems.
				167	Still, if you want to experiment with AppleEvents right now: go ahead!
				168	<p>