1 

     2 .. _mac-scripting:

     3 

     4 *********************

     5 MacPython OSA Modules

     6 *********************

     7 

     8 This chapter describes the current implementation of the Open Scripting

     9 Architecture (OSA, also commonly referred to as AppleScript) for Python,

    10 allowing you to control scriptable applications from your Python program,

    11 and with a fairly pythonic interface. Development on this set of modules has

    12 stopped, and a replacement is expected for Python 2.5.

    13 

    14 For a description of the various components of AppleScript and OSA, and to get

    15 an understanding of the architecture and terminology, you should read Apple's

    16 documentation. The "Applescript Language Guide" explains the conceptual model

    17 and the terminology, and documents the standard suite. The "Open Scripting

    18 Architecture" document explains how to use OSA from an application programmers

    19 point of view. In the Apple Help Viewer these books are located in the Developer

    20 Documentation, Core Technologies section.

    21 

    22 As an example of scripting an application, the following piece of AppleScript

    23 will get the name of the frontmost :program:`Finder` window and print it::

    24 

    25    tell application "Finder"

    26        get name of window 1

    27    end tell

    28 

    29 In Python, the following code fragment will do the same::

    30 

    31    import Finder

    32 

    33    f = Finder.Finder()

    34    print f.get(f.window(1).name)

    35 

    36 As distributed the Python library includes packages that implement the standard

    37 suites, plus packages that interface to a small number of common applications.

    38 

    39 To send AppleEvents to an application you must first create the Python package

    40 interfacing to the terminology of the application (what :program:`Script Editor`

    41 calls the "Dictionary"). This can be done from within the :program:`PythonIDE`

    42 or by running the :file:`gensuitemodule.py` module as a standalone program from

    43 the command line.

    44 

    45 The generated output is a package with a number of modules, one for every suite

    46 used in the program plus an :mod:`__init__` module to glue it all together. The

    47 Python inheritance graph follows the AppleScript inheritance graph, so if a

    48 program's dictionary specifies that it includes support for the Standard Suite,

    49 but extends one or two verbs with extra arguments then the output suite will

    50 contain a module :mod:`Standard_Suite` that imports and re-exports everything

    51 from :mod:`StdSuites.Standard_Suite` but overrides the methods that have extra

    52 functionality. The output of :mod:`gensuitemodule` is pretty readable, and

    53 contains the documentation that was in the original AppleScript dictionary in

    54 Python docstrings, so reading it is a good source of documentation.

    55 

    56 The output package implements a main class with the same name as the package

    57 which contains all the AppleScript verbs as methods, with the direct object as

    58 the first argument and all optional parameters as keyword arguments. AppleScript

    59 classes are also implemented as Python classes, as are comparisons and all the

    60 other thingies.

    61 

    62 The main Python class implementing the verbs also allows access to the

    63 properties and elements declared in the AppleScript class "application". In the

    64 current release that is as far as the object orientation goes, so in the example

    65 above we need to use ``f.get(f.window(1).name)`` instead of the more Pythonic

    66 ``f.window(1).name.get()``.

    67 

    68 If an AppleScript identifier is not a Python identifier the name is mangled

    69 according to a small number of rules:

    70 

    71 * spaces are replaced with underscores

    72 

    73 * other non-alphanumeric characters are replaced with ``_xx_`` where ``xx`` is

    74   the hexadecimal character value

    75 

    76 * any Python reserved word gets an underscore appended

    77 

    78 Python also has support for creating scriptable applications in Python, but The

    79 following modules are relevant to MacPython AppleScript support:

    80 

    81 .. toctree::

    82 

    83    gensuitemodule.rst

    84    aetools.rst

    85    aepack.rst

    86    aetypes.rst

    87    miniaeframe.rst

    88 

    89 

    90 In addition, support modules have been pre-generated for :mod:`Finder`,

    91 :mod:`Terminal`, :mod:`Explorer`, :mod:`Netscape`, :mod:`CodeWarrior`,

    92 :mod:`SystemEvents` and :mod:`StdSuites`.