Mercurial > cpython-lru_cache-weakref

annotate Doc/mac/scripting.tex @ 39042:c02fa187e0f4 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Part of SF patch #1484695. This removes dead code. The chksum was already verified in .frombuf() on the lines above. If there was a problem an exception is raised, so there was no way this condition could have been true.
author Neal Norwitz <nnorwitz@gmail.com>
date Mon, 10 Jul 2006 00:23:17 +0000
parents 628f41a8b1ce
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
28578
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
1 \chapter{MacPython OSA Modules \label{scripting}}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
2
34586
7e7e86f45255 Update refences to "Macintosh" to reflect the state of affairs for OS X and not
Brett Cannon <bcannon@gmail.com>
parents: 34450
diff changeset
3 This chapter describes the current implementation of the Open Scripting
7e7e86f45255 Update refences to "Macintosh" to reflect the state of affairs for OS X and not
Brett Cannon <bcannon@gmail.com>
parents: 34450
diff changeset
4 Architecure (OSA, also commonly referred to as AppleScript) for Python, allowing
28578
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
5 you to control scriptable applications from your Python program,
34586
7e7e86f45255 Update refences to "Macintosh" to reflect the state of affairs for OS X and not
Brett Cannon <bcannon@gmail.com>
parents: 34450
diff changeset
6 and with a fairly pythonic interface. Development on this set of modules
7e7e86f45255 Update refences to "Macintosh" to reflect the state of affairs for OS X and not
Brett Cannon <bcannon@gmail.com>
parents: 34450
diff changeset
7 has stopped, and a replacement is expected for Python 2.5.
28578
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
8
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
9 For a description of the various components of AppleScript and OSA, and
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
10 to get an understanding of the architecture and terminology, you should
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
11 read Apple's documentation. The "Applescript Language Guide" explains
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
12 the conceptual model and the terminology, and documents the standard
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
13 suite. The "Open Scripting Architecture" document explains how to use
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
14 OSA from an application programmers point of view. In the Apple Help
37912
628f41a8b1ce Typo fixes
Andrew M. Kuchling <amk@amk.ca>
parents: 34586
diff changeset
15 Viewer these books are located in the Developer Documentation, Core
28578
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
16 Technologies section.
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
17
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
18
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
19 As an example of scripting an application, the following piece of
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
20 AppleScript will get the name of the frontmost \program{Finder} window
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
21 and print it:
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
22
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
23 \begin{verbatim}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
24 tell application "Finder"
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
25 get name of window 1
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
26 end tell
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
27 \end{verbatim}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
28
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
29 In Python, the following code fragment will do the same:
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
30
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
31 \begin{verbatim}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
32 import Finder
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
33
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
34 f = Finder.Finder()
29434
e69e54552d10 Documented the fact that the main class now mimicks the OSA "application" class.
Jack Jansen <jack.jansen@cwi.nl>
parents: 28578
diff changeset
35 print f.get(f.window(1).name)
28578
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
36 \end{verbatim}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
37
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
38 As distributed the Python library includes packages that implement the
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
39 standard suites, plus packages that interface to a small number of
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
40 common applications.
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
41
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
42 To send AppleEvents to an application you must first create the Python
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
43 package interfacing to the terminology of the application (what
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
44 \program{Script Editor} calls the "Dictionary"). This can be done from
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
45 within the \program{PythonIDE} or by running the
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
46 \file{gensuitemodule.py} module as a standalone program from the command
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
47 line.
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
48
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
49 The generated output is a package with a number of modules, one for
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
50 every suite used in the program plus an \module{__init__} module to glue
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
51 it all together. The Python inheritance graph follows the AppleScript
37912
628f41a8b1ce Typo fixes
Andrew M. Kuchling <amk@amk.ca>
parents: 34586
diff changeset
52 inheritance graph, so if a program's dictionary specifies that it
28578
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
53 includes support for the Standard Suite, but extends one or two verbs
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
54 with extra arguments then the output suite will contain a module
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
55 \module{Standard_Suite} that imports and re-exports everything from
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
56 \module{StdSuites.Standard_Suite} but overrides the methods that have
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
57 extra functionality. The output of \module{gensuitemodule} is pretty
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
58 readable, and contains the documentation that was in the original
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
59 AppleScript dictionary in Python docstrings, so reading it is a good
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
60 source of documentation.
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
61
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
62 The output package implements a main class with the same name as the
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
63 package which contains all the AppleScript verbs as methods, with the
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
64 direct object as the first argument and all optional parameters as
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
65 keyword arguments. AppleScript classes are also implemented as Python
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
66 classes, as are comparisons and all the other thingies.
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
67
29434
e69e54552d10 Documented the fact that the main class now mimicks the OSA "application" class.
Jack Jansen <jack.jansen@cwi.nl>
parents: 28578
diff changeset
68 The main
e69e54552d10 Documented the fact that the main class now mimicks the OSA "application" class.
Jack Jansen <jack.jansen@cwi.nl>
parents: 28578
diff changeset
69 Python class implementing the verbs also allows access to the properties
e69e54552d10 Documented the fact that the main class now mimicks the OSA "application" class.
Jack Jansen <jack.jansen@cwi.nl>
parents: 28578
diff changeset
70 and elements declared in the AppleScript class "application". In the
e69e54552d10 Documented the fact that the main class now mimicks the OSA "application" class.
Jack Jansen <jack.jansen@cwi.nl>
parents: 28578
diff changeset
71 current release that is as far as the object orientation goes, so
e69e54552d10 Documented the fact that the main class now mimicks the OSA "application" class.
Jack Jansen <jack.jansen@cwi.nl>
parents: 28578
diff changeset
72 in the example above we need to use
31197
6845697353a3 fix typo
Fred Drake <fdrake@acm.org>
parents: 29434
diff changeset
73 \code{f.get(f.window(1).name)} instead of the more Pythonic
28578
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
74 \code{f.window(1).name.get()}.
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
75
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
76
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
77 If an AppleScript identifier is not a Python identifier the name is
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
78 mangled according to a small number of rules:
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
79 \begin{itemize}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
80 \item spaces are replaced with underscores
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
81 \item other non-alphanumeric characters are replaced with
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
82 \code{_xx_} where \code{xx} is the hexadecimal character value
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
83 \item any Python reserved word gets an underscore appended
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
84 \end{itemize}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
85
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
86 Python also has support for creating scriptable applications
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
87 in Python, but
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
88 The following modules are relevant to MacPython AppleScript support:
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
89
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
90 \localmoduletable
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
91
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
92 In addition, support modules have been pre-generated for
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
93 \module{Finder}, \module{Terminal}, \module{Explorer},
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
94 \module{Netscape}, \module{CodeWarrior}, \module{SystemEvents} and
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
95 \module{StdSuites}.
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
96
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
97 \input{libgensuitemodule}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
98 \input{libaetools}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
99 \input{libaepack}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
100 \input{libaetypes}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
101 \input{libminiae}