Mercurial > cpython-lru_cache-weakref

annotate Doc/mac/scripting.tex @ 28646:193b8aec00ce legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Changes from Jonathan Riehl to allow his pgen extension (PEP 269) to work. This includes some more code that used to be part of pgen in the main parser; I'm okay with that. I'll see if the Windows build needs work next.
author Guido van Rossum <guido@python.org>
date Thu, 17 Apr 2003 14:55:42 +0000
parents 8b49445c0a0e
children e69e54552d10
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()
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
34 print f.get(Finder.window(1).name)
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
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
67 Note that in the current release there is no coupling between the main
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
68 Python class implementing the verbs and the Python classes implementing
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
69 the AppleScript classes. Hence, in the example above we need to use
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
70 \code{f.get(Finder.window(1).name)} in stead of the more Pythonic
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
71 \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
72
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
73
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
74 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
75 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
76 \begin{itemize}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
77 \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
78 \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
79 \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
80 \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
81 \end{itemize}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
82
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
83 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
84 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
85 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
86
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
87 \localmoduletable
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 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
90 \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
91 \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
92 \module{StdSuites}.
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
93
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
94 \input{libgensuitemodule}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
95 \input{libaetools}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
96 \input{libaepack}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
97 \input{libaetypes}
8b49445c0a0e Moved all the scripting stuff to a separate section, added all the
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
98 \input{libminiae}