Mercurial > cpython-lru_cache-weakref

annotate Doc/mac/scripting.tex @ 33845:032f342efcd2 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Very few little improvements.
author Facundo Batista <facundobatista@gmail.com>
date Tue, 26 Oct 2004 23:38:46 +0000
parents 6845697353a3
children 2931f6504af5
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
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
3 Python has a fairly complete implementation of the Open Scripting
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
4 Architecure (OSA, also commonly referred to as AppleScript), allowing
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,
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
6 and with a fairly pythonic interface.
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
7
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
8 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
9 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
10 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
11 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
12 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
13 OSA from an application programmers point of view. In the Apple Help
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
14 Viewer these book sare located in the Developer Documentation, Core
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
15 Technologies section.
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
16
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 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
19 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
20 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
21
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
22 \begin{verbatim}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
23 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
24 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
25 end tell
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
26 \end{verbatim}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
27
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
28 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
29
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
30 \begin{verbatim}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
31 import Finder
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
32
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
33 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
34 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
35 \end{verbatim}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
36
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
37 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
38 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
39 common applications.
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
40
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
41 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
42 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
43 \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
44 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
45 \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
46 line.
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
47
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
48 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
49 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
50 it all together. The Python inheritance graph follows the AppleScript
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
51 inheritance graph, so if a programs dictionary specifies that it
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
52 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
53 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
54 \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
55 \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
56 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
57 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
58 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
59 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
60
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
61 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
62 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
63 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
64 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
65 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
66
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
67 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
68 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
69 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
70 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
71 in the example above we need to use
31197
6845697353a3 fix typo
Fred Drake <fdrake@acm.org>
parents: 29434
diff changeset
72 \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
73 \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
74
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 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
77 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
78 \begin{itemize}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
79 \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
80 \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
81 \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
82 \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
83 \end{itemize}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
84
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
85 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
86 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
87 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
88
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
89 \localmoduletable
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
90
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
91 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
92 \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
93 \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
94 \module{StdSuites}.
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
95
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
96 \input{libgensuitemodule}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
97 \input{libaetools}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
98 \input{libaepack}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
99 \input{libaetypes}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
100 \input{libminiae}