py-appscript manual | 4. Getting help

#

## 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

- While appscript's help tools try to be reasonably forgiving of flawed or faulty terminology resources, there may be a few particularly problematic applications on which they fail. Should this happen, you can use ASDictionary to export the application's terminology in plain text format instead.
- Appscript is not pydoc-compatible. Passing appscript references to Python's built-in `help` function will result in an error.

### Other sources of help

- The `Examples` folder contains example scripts demonstrating a range of common tasks.
- Refer to any scripting documentation and example scripts supplied by the application developer.
- Look for third-party scripts that provide examples of use (though many of these scripts will be written in AppleScript rather than Python).
- The appscript website has links to mailing lists and other general resources.