py-appscript manual | 11. Application commands

#

## 11. Application commands

### Command syntax

For convenience, appscript makes application commands available as methods on every reference. (Note: due to the limitations of aete-based terminology, the user must determine for themselves which commands can operate on a particular reference. Some applications document this information separately.)

    reference.command_name(*arg, **args, waitreply=True,
             timeout=60, resulttype=None, ignore=None)
        *arg : anything -- direct arg, if any
        **kwargs : anything -- labelled arg(s), if any
        waitreply : bool -- wait for application to return a result/error?
        canaskforconsent : bool -- can appscript ask user for permission
                                   if needed to control target application?
        timeout : int -- no. of seconds to wait for a reply
        resulttype : None | Keyword -- AE type to coerce return value to
        ignore : None | list of Keyword -- string characteristics to ignore
                                           when evaluating references
        Result : anything -- value returned by application, if any

*arg
  An application command can have either zero or one direct parameters. The application's dictionary indicates which commands take a direct parameter, and if it is optional or required.
**kwargs
  An application command can have zero or more labelled parameters. The application's dictionary describes the labelled parameters for each command, and if they are optional or required.
waitreply
  If `True` (the default), appscript will wait for the application to reply to the command. If `False`, it will return as soon as the command is sent, ignoring any return values or application errors.
canaskforconsent
  In macOS 10.14+, if `True` (the default), allows the process running this script to ask the user for permission to control the target application when sending its first command. If `False`, the command will only be sent if permission has previously been granted, otherwise an error -1744 (event would require users consent) will occur. Ignored in 10.13 and earlier. Note that this option only applies to commands defined by the application. The standard commands recognized by all Mac applications (`run`, `open`, `quit`, etc.) are not affected. See the System Integrity Protection section in Chapter 14 for more information.
timeout
  The number of seconds to wait for the application to reply before raising a timeout error. The default is 60 seconds but may be increased or decreased as needed; Use 0 to wait indefinitely. For example, a longer timeout may be needed to prevent a timeout error occurring during a particularly long-running application command. Note: due to a quirk in the Apple Event Manager API, timeout errors may be reported as either error -1712 (the Apple event timed out) or -609 (connection invalid, which is also raised when an application unexpectedly quits while handling a command).
resulttype
  Some applications may allow the return value's type to be specified for certain commands (typically `get`). For example, the Finder's `get` command returns filesystem references as alias objects if the resulttype is `k.alias`.
ignore
  Some applications may allow the client to specify text attributes that should be considered or ignored when performing string comparisons, e.g. when resolving by-test references. When specifying the attributes to ignore, the list should contain zero or more of the following enumerators: `k.case`, `k.diacriticals`, `k.expansion`, `k.hyphens`, `k.punctuation`, `k.whitespace`. Note that most applications currently ignore this setting and always use the default behaviour, which is to ignore case but consider everything else.

### Examples

    # tell application "TextEdit" to activate
    app('TextEdit').activate()

    # tell application "TextEdit" to open fileRefList
    app('TextEdit').open(fileRefList)

    # tell application "Finder" to get version
    app('Finder').version.get()

    # tell application "Finder" to set name of file "foo.txt" of home to "bar.txt"
    app('Finder').home.files['foo.txt'].name.set('bar.txt')

    # tell application "TextEdit" to count (text of first document) each paragraph
    app('TextEdit').documents.first.text.count(each=k.paragraph)

    # tell application "TextEdit" to make new document at end of documents
    app('TextEdit').documents.end.make(new=k.document)

    # tell application "Finder" to get items of home as alias list
    app('Finder').home.items.get(resulttype=k.alias)

### Special cases

The following special-case behaviours are implemented for convenience:

1. Commands that take a reference to one or more application objects as a direct parameter may be written in the following form:

       reference.command(**keyword_parameters)

   The conventional form is also supported should you ever wish (or need) to use it:

       application.command(reference, **keyword_parameters)

   The two forms are equivalent (appscript converts the first form to the second behind the scenes) although the first form is preferred for conciseness.

2. If a command that already has a direct parameter is called on a reference, i.e.:

       reference.command(direct_parameter, **keyword_parameters)

   the reference upon which it is called will be packed as the Apple event's 'subject' attribute (`keySubjectAttr`).

3. The `set` command may pass its `to` parameter as a direct rather than labelled argument if there is no other direct parameter and no other labelled `to` parameter; i.e.:

       reference.set(value)

   instead of:

       reference.set(to=value)

   or:

       application.set(reference, to=value)

   The first form is preferred, although all three are supported.

4. If the `make` command is called on an insertion location reference, appscript will pack that reference as the Apple event's `at` parameter if it doesn't already have one; i.e.:

       insertion_location.make(new=class)

   is equivalent to:

       application.make(new=class, at=insertion_location)

   If the `make` command is called on an object reference, appscript will pack that reference as the Apple event's 'subject' attribute. (Note that some applications may not handle the subject attribute correctly, in which case the reference should be passed as the `make` command's `at` parameter instead.)

5. Calling a reference directly is equivalent to invoking its `get` command. For example:

       reference()

   is the same as:

       reference.get()

### Command errors

The `appscript.CommandError` exception describes an error raised by the target application or Apple Event Manager when sending a command.

    CommandError(Exception)

        Properties:
            errornumber : int -- Mac OS error number
            errormessage : str -- application-supplied/generic error description
            offendingobject : anything | None -- object that caused the error,
                                                 if given by application
            expectedtype : anything | None -- object that caused a coercion error,
                                              if given by application
            partialresult : anything | None -- part of return value constructed
                                               before error occurred, if given
                                               by application

        Methods:

            __int__() -- Mac OS error number

            __str__() -- formatted description of error

### Note to AppleScript users

Unlike AppleScript, which implicitly sends a `get` command to any unresolved application object references at the end of evaluating an expression, appscript only resolves a reference when it receives an appropriate command. For example:

    d = app('TextEdit').documents

is not the same as:

    set d to documents of app "TextEdit"

even though the two may look similar. In the first case, the value assigned to `d` is an appscript reference: `app('TextEdit').documents`. In the second, AppleScript evaluates the `documents of app "TextEdit"` reference by performing an implicit `get` command and then assigning its result, a list of references to individual documents, to `d`. To obtain the original reference as an AppleScript value, the literal reference must be preceded by an `a reference to` operator as shown below.

To get a single reference to all documents:

    set d to a reference to documents of app "TextEdit"
    return d
    --> a reference to documents of app "TextEdit"

    d = app('TextEdit').documents
    print d
    --> app('TextEdit').documents

To get a list of references to each document:

    set d to get documents of app "TextEdit" -- (explicit 'get' is optional)
    return d
    --> {document 1 of app "TextEdit", document 2 of app "TextEdit"}

    d = app('TextEdit').documents.get() -- (explicit 'get' is required)
    print d
    --> [app('TextEdit').documents[1], app('TextEdit').documents[2]]