py-appscript

4. Getting help

When developing appscript-based scripts, there are several related tools that can assist you: the ASDictionary application, appscript's powerful built-in help method, and the ASTranslate application.

ASDictionary

ASDictionary, available from the appscript website's tools page, provides a convenient GUI interface for exporting application terminology resources in plain text and HTML formats. ASDictionary can export HTML dictionaries in both single-file and frame-based formats.

Built-in help

Appscript's Application and Reference classes include a powerful interactive help system that allows you to explore applications' scripting interfaces in the Python interpreter while you work. The help method can provide information on any suite, class, command or reference, and display the inheritance and relationships for a selected class or the entire application.

Note that py-appscript's built-in help system is only available when ASDictionary 0.12.0 or later is installed. If ASDictionary isn't available or is too old, invoking help will simply result in a "No help available" message and the script will continue to run as normal.

Built-in help is invoked by calling an app object's help method, optionally passing it a string indicating the type of information you want. The resulting help message is printed to stderr and script execution continues as normal. For example, to view the help system's own help, call the help method with '-h' as its argument:

app('TextEdit').help('-h')

To print a description of any class or command or view inheritance and relationships, pass the help method a help string containing one or more of the following options:

-h
show help
-o
overview of all suites, classes and commands
-k
list all built-in keywords (type names)
-u [suite-name]
summary of named suite or all suites
-t [class-or-command-name]
terminology for named class/command or current reference/command
-i [class-name]
inheritance tree for named class or all classes
-r [class-name]
one-to-one and one-to-many relationships for named class or current reference
-s [property-or-element-name]
values of properties and elements of object(s) currently referenced

Arguments (shown in brackets) are optional. Additional information on usage is available via help('-h').

Examples:

app('Finder').help('-o')
app('Finder').help('-t window')
app('Finder').files.help() # same as help('-t')
app('Finder').help('-d item -r folder -i container')
app('Finder').files.help('-s')
app('Finder').files.get.help('-s')()

To print detailed information on a specific reference, call its help method without arguments. Examples:

app('TextEdit').help()
app('TextEdit').version.help()
app('TextEdit').documents.help()
app('TextEdit').documents.count.help()

Tip: help calls can safely be inserted at any point in a reference without disrupting your script's execution:

c = app('TextEdit').help().help('-o -i -s'). \
        documents.help()[1].help().count.help()()

ASTranslate

ASTranslate, available from the appscript website's tools page, provides a simple tool for translating application commands from AppleScript to Python syntax - useful when help is needed in converting existing AppleScript code to Python. For example, the following AppleScript selects every file in the Home folder:

tell application "Finder"
    select (every file of home whose name extension is in {"htm", "html"})
end tell

To obtain the appscript equivalent, paste this script into ASTranslate and select Execute from the Document menu. ASTranslate will intercept any Apple events sent by AppleScript and display them in appscript format:

app('Finder').home.files[its.name_extension.isin(['htm', 'html'])].select()

See ASTranslate's documentation for more information.

Notes

Other sources of help