plover-run-applescript 0.3.11

Description:

ploverrunapplescript 0.3.11

Plover Run AppleScript

This Plover extension plugin contains a command that can run
AppleScript code, as well as load in and run external AppleScript files.
Install

In the Plover application, open the Plugins Manager (either click the Plugins
Manager icon, or from the Tools menu, select Plugins Manager).
From the list of plugins, find plover-run-applescript
Click "Install/Update"
When it finishes installing, restart Plover
After re-opening Plover, open the Configuration screen (either click the
Configuration icon, or from the main Plover application menu, select
Preferences...)
Open the Plugins tab
Check the box next to plover_run_applescript to activate the plugin

How To Use
One-Liners
If your AppleScript is one line long, then you can use the code directly in your
steno dictionary entry in the following way:
"KR-PL": "{:COMMAND:APPLESCRIPT:activate application \"Google Chrome\"}"

AppleScript Files
To run code in AppleScript files, create steno dictionary entry values that look
like the following:
"KPH-PBD": "{:COMMAND:APPLESCRIPT:/path/to/your/applescript-file.scpt}"


[!NOTE]
You can compile your .applescript files into .scpt files using the
osacompile tool:
osacompile -o my-file.scpt my-file.applescript


The path to your AppleScript file can contain a local $ENVIRONMENT_VARIABLE,
which will get expanded. For example, if you have a line like the following in
your .zshrc file:
export STENO_DICTIONARIES="$HOME/steno/steno-dictionaries"

You can use it in the command:
"KPH-PBD": "{:COMMAND:APPLESCRIPT:$STENO_DICTIONARIES/path/to/applescript-file.scpt}"

Sending Commands
If you want to test out a command before adding a steno dictionary entry
containing it, you can use Plover's plover_send_command command-line tool.
For example:
plover --script plover_send_command "APPLESCRIPT:activate application \"Google Chrome\""
plover --script plover_send_command "APPLESCRIPT:/path/to/your/applescript-file.scpt"


Where plover in the command is a reference to your locally installed version
of Plover. See the Invoke Plover from the command line page for details on
how to create that reference.

Pressing the "Disconnect and reconnect the machine" button on the Plover UI
resets the AppleScript script cache. If you make any changes to any AppleScript
files, make sure to press it so the file will be re-read in again.

[!WARNING]
Due to this issue with PyXA, which this plugin relies on to talk to
Apple's APIs, any AppleScript files that are referenced in a Plover outline
cannot contain lists in the code (denoted by curly braces; e.g.
{"one", "two"}).
So, if you have code that looks like this:
keystroke "k" using {command down, shift down}

You will have to re-write it out longhand to be able to use it with this
plugin, like so:
key down command
key down shift
keystroke "k"
key up shift
key up command

Or, extract the code you have that uses lists out into script libraries.
I wrote about how I did this in Sharing AppleScript Handlers.
Update: The AppleScript-related issues have now been fixed, as can be seen
in the issue. However, since those fixes are only in a version of PyXA that
uses a Python version later than 3.9, we will have to wait until the Python
version bundled in with Plover itself updates to at least 3.10 before this
problem can be properly resolved.

The Problem
The following is an example of how I used to run AppleScripts from my Plover
dictionaries to perform some kind of automation task that could only be
done on macOS using AppleScript:
"W-D": "{:COMMAND:SHELL:bash -ci 'osascript $STENO_DICTIONARIES/src/command/text/move-one-word-forward.scpt'}"

This solution does the following:

uses the Plover Run Shell plugin to run a shell command from Python
calls bash in interactive mode (-i) so that the command can see
environment variables ($STENO_DICTIONARIES in this case) outside of the
Plover environment
gets bash to use the osascript command-line tool to load in and run
the target compiled AppleScript (.scpt file)

Running AppleScripts is generally slow, and constantly running one-off
commands that traverse a stack of Python->Shell->osascript made them even
slower.
So, this plugin leverages PyXA to talk directly to Apple's APIs from Python,
and keeps a local cache of loaded scripts to avoid needing to re-read in
AppleScript files every time a command is run.
The above command now looks like this:
"W-D": "{:COMMAND:APPLESCRIPT:$STENO_DICTIONARIES/src/command/text/move-one-word-forward.scpt}"

Development
Clone from GitHub with git:
git clone [email protected]:paulfioravanti/plover-run-applescript.git
cd plover-run-applescript
python -m pip install --editable ".[test]"

If you are a Tmuxinator user, you may find my plover_run_applescript
project file of reference.
Python Version
Plover's Python environment currently uses version 3.9 (see Plover's
workflow_context.yml to confirm the current version).
So, in order to avoid unexpected issues, use your runtime version manager to
make sure your local development environment also uses Python 3.9.x.
PyXA Version
This plugin depends on PyXA for all Python-to-AppleScript interoperations.
The dependency is currently pinned at version 0.0.9 due to later versions
of PyXA using Python 3.10 syntax (match case etc) that is too new for
Plover's Python version, and causes syntax errors.
Testing

Pytest is used for testing in this plugin.
Coverage.py and pytest-cov are used for test coverage, and to run
coverage within Pytest
Pylint is used for code quality
Mypy is used for static type checking

Currently, the only parts able to be tested are ones that do not rely directly
on Plover or PyXA.
Run tests, coverage, and linting with the following commands:
pytest --cov --cov-report=term-missing
pylint plover_run_applescript
mypy plover_run_applescript

To get a HTML test coverage report:
coverage run --module pytest
coverage html
open htmlcov/index.html

If you are a just user, you may find the justfile useful during
development in running multiple test commands. You can run the following command
from the project root directory:
just --working-directory . --justfile test/justfile

Deploying Changes
After making any code changes, install the plugin into Plover with the following
command:
plover --script plover_plugins install --editable .


Where plover in the command is a reference to your locally installed version
of Plover. See the Invoke Plover from the command line page for details on
how to create that reference.

When necessary, the plugin can be uninstalled via the command line with the
following command:
plover --script plover_plugins uninstall plover-run-applescript