py-appscript

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