# Plover Run AppleScript
[![Build Status][Build Status image]][Build Status url] [![PyPI - Version][PyPI version image]][PyPI url] [![PyPI - Downloads][PyPI downloads image]][PyPI url] [![linting: pylint][linting image]][linting url]
This [Plover][] [extension][] [plugin][] contains a [command][] that can load in
and run external [AppleScript][] files.
## Install
1. In the Plover application, open the Plugins Manager (either click the Plugins
Manager icon, or from the `Tools` menu, select `Plugins Manager`).
2. From the list of plugins, find `plover-run-applescript`
3. Click "Install/Update"
4. When it finishes installing, restart Plover
5. After re-opening Plover, open the Configuration screen (either click the
Configuration icon, or from the main Plover application menu, select
`Preferences...`)
6. Open the Plugins tab
7. 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 it directly in your
dictionary entry:
```json
"{:COMMAND:APPLESCRIPT:activate application \"Google Chrome\"}"
```
### AppleScript Files
In your dictionaries, create entry values that look like the following:
```json
"{:COMMAND:APPLESCRIPT:/path/to/your/applescript-file.scpt}"
```
> [!NOTE]
> You can compile your `.applescript` files into [`.scpt`][] files using the
> [`osacompile`][] tool:
>
> ```console
> 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:
```sh
export STENO_DICTIONARIES="$HOME/steno/steno-dictionaries"
```
You can use it in the command:
```json
"{:COMMAND:APPLESCRIPT:$STENO_DICTIONARIES/path/to/applescript-file.scpt}"
```
> [!WARNING]
> Due to an [issue with PyXA][], which this plugin relies on to talk to Apple's
> APIs, your AppleScript files cannot use lists (denoted by curly braces; e.g.
> `{"one", "two"}`).
>
> So, if you have code that looks like this:
>
> ```applescript
> 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:
>
> ```applescript
> 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][]_.
>
> If/when the issue gets fixed, you should be able to use lists again...
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.
## 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:
```json
"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:
```json
"W-D": "{:COMMAND:APPLESCRIPT:$STENO_DICTIONARIES/src/command/text/move-one-word-forward.scpt}"
```
The result is that commands at least _feel_ like they run significantly faster,
and I'm pretty sure it's because they actually are (but I don't have any hard
benchmarks to objectively prove this).
## Development
Clone from GitHub with [git][]:
```console
git clone git@github.com:paulfioravanti/plover-run-applescript.git
cd plover-run-applescript
```
### 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:
```console
pytest --cov --cov-report=term-missing
pylint plover_run_applescript
mypy plover_run_applescript
```
To get a HTML test coverage report:
```console
coverage run --module pytest
coverage html
open htmlcov/index.html
```
If you get `ModuleNotFoundError: No module named 'PyXA'` errors, then run the
following command to get PyXA available in your test environment:
```console
pip install -e ".[test]"
```
### Deploying Changes
After making any code changes, install the plugin into Plover with the following
command:
```sh
plover -s plover_plugins install .
```
> 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.
[AppleScript]: https://en.wikipedia.org/wiki/AppleScript
[Build Status image]: https://github.com/paulfioravanti/plover-run-applescript/actions/workflows/ci.yml/badge.svg
[Build Status url]: https://github.com/paulfioravanti/plover-run-applescript/actions/workflows/ci.yml
[command]: https://plover.readthedocs.io/en/latest/plugin-dev/commands.html
[Coverage.py]: https://github.com/nedbat/coveragepy
[environment variables]: https://en.wikipedia.org/wiki/Environment_variable
[extension]: https://plover.readthedocs.io/en/latest/plugin-dev/extensions.html
[git]: https://git-scm.com/
[interactive mode]: https://www.gnu.org/software/bash/manual/html_node/Interactive-Shell-Behavior.html
[Invoke Plover from the command line]: https://github.com/openstenoproject/plover/wiki/Invoke-Plover-from-the-command-line
[issue with PyXA]: https://github.com/SKaplanOfficial/PyXA/issues/16
[linting image]: https://img.shields.io/badge/linting-pylint-yellowgreen
[linting url]: https://github.com/pylint-dev/pylint
[macOS]: https://en.wikipedia.org/wiki/MacOS
[`match case`]: https://peps.python.org/pep-0636/
[my Plover dictionaries]: https://github.com/paulfioravanti/steno-dictionaries/tree/main
[Mypy]: https://github.com/python/mypy
[`osacompile`]: https://ss64.com/osx/osacompile.html
[`osascript`]: https://ss64.com/osx/osascript.html
[Plover]: https://www.openstenoproject.org/
[Plover Run Shell]: https://github.com/user202729/plover_run_shell
[plugin]: https://plover.readthedocs.io/en/latest/plugins.html#types-of-plugins
[Pylint]: https://github.com/pylint-dev/pylint
[PyPI downloads image]:https://img.shields.io/pypi/dm/plover-run-applescript
[PyPI version image]: https://img.shields.io/pypi/v/plover-run-applescript
[PyPI url]: https://pypi.org/project/plover-run-applescript/
[Pytest]: https://pytest.org/
[pytest-cov]: https://github.com/pytest-dev/pytest-cov/
[PyXA]: https://github.com/SKaplanOfficial/PyXA
[`.scpt`]: https://fileinfo.com/extension/scpt
[script libraries]: https://developer.apple.com/library/archive/documentation/LanguagesUtilities/Conceptual/MacAutomationScriptingGuide/UseScriptLibraries.html
[Sharing AppleScript Handlers]: https://www.paulfioravanti.com/blog/sharing-applescript-handlers/
[version 0.0.9]: https://github.com/SKaplanOfficial/PyXA/tree/v0.0.9
[`workflow_context.yml`]: https://github.com/openstenoproject/plover/blob/master/.github/workflows/ci/workflow_context.yml
Raw data
{
"_id": null,
"home_page": "https://github.com/paulfioravanti/plover-run-applescript",
"name": "plover-run-applescript",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "plover plover_plugin",
"author": "Paul Fioravanti",
"author_email": "paul@paulfioravanti.com",
"download_url": "https://files.pythonhosted.org/packages/e9/f3/884a34b17d88aeab63fe532a6eb2b1dcd1f024e2d32de8f74b3a89a1dd63/plover_run_applescript-0.3.4.tar.gz",
"platform": null,
"description": "# Plover Run AppleScript\n\n[![Build Status][Build Status image]][Build Status url] [![PyPI - Version][PyPI version image]][PyPI url] [![PyPI - Downloads][PyPI downloads image]][PyPI url] [![linting: pylint][linting image]][linting url]\n\nThis [Plover][] [extension][] [plugin][] contains a [command][] that can load in\nand run external [AppleScript][] files.\n\n## Install\n\n1. In the Plover application, open the Plugins Manager (either click the Plugins\n Manager icon, or from the `Tools` menu, select `Plugins Manager`).\n2. From the list of plugins, find `plover-run-applescript`\n3. Click \"Install/Update\"\n4. When it finishes installing, restart Plover\n5. After re-opening Plover, open the Configuration screen (either click the\n Configuration icon, or from the main Plover application menu, select\n `Preferences...`)\n6. Open the Plugins tab\n7. Check the box next to `plover_run_applescript` to activate the plugin\n\n## How To Use\n\n### One-Liners\n\nIf your AppleScript is one line long, then you can use it directly in your\ndictionary entry:\n\n```json\n\"{:COMMAND:APPLESCRIPT:activate application \\\"Google Chrome\\\"}\"\n```\n\n### AppleScript Files\n\nIn your dictionaries, create entry values that look like the following:\n\n```json\n\"{:COMMAND:APPLESCRIPT:/path/to/your/applescript-file.scpt}\"\n```\n\n> [!NOTE]\n> You can compile your `.applescript` files into [`.scpt`][] files using the\n> [`osacompile`][] tool:\n>\n> ```console\n> osacompile -o my-file.scpt my-file.applescript\n> ```\n\nThe path to your AppleScript file can contain a local `$ENVIRONMENT_VARIABLE`,\nwhich will get expanded. For example, if you have a line like the following in\nyour `.zshrc` file:\n\n```sh\nexport STENO_DICTIONARIES=\"$HOME/steno/steno-dictionaries\"\n```\n\nYou can use it in the command:\n\n```json\n\"{:COMMAND:APPLESCRIPT:$STENO_DICTIONARIES/path/to/applescript-file.scpt}\"\n```\n\n> [!WARNING]\n> Due to an [issue with PyXA][], which this plugin relies on to talk to Apple's\n> APIs, your AppleScript files cannot use lists (denoted by curly braces; e.g.\n> `{\"one\", \"two\"}`).\n>\n> So, if you have code that looks like this:\n>\n> ```applescript\n> keystroke \"k\" using {command down, shift down}\n> ```\n>\n> You will have to re-write it out longhand to be able to use it with this\n> plugin, like so:\n>\n> ```applescript\n> key down command\n> key down shift\n> keystroke \"k\"\n> key up shift\n> key up command\n> ```\n>\n> Or, extract the code you have that uses lists out into [script libraries][].\n> I wrote about how I did this in _[Sharing AppleScript Handlers][]_.\n>\n> If/when the issue gets fixed, you should be able to use lists again...\n\nPressing the \"Disconnect and reconnect the machine\" button on the Plover UI\nresets the AppleScript script cache. If you make any changes to any AppleScript\nfiles, make sure to press it so the file will be re-read in again.\n\n## The Problem\n\nThe following is an example of how I used to run AppleScripts from [my Plover\ndictionaries][] to perform some kind of automation task that could _only_ be\ndone on [macOS][] using AppleScript:\n\n```json\n\"W-D\": \"{:COMMAND:SHELL:bash -ci 'osascript $STENO_DICTIONARIES/src/command/text/move-one-word-forward.scpt'}\"\n```\n\nThis solution does the following:\n\n- uses the [Plover Run Shell][] plugin to run a shell command from Python\n- calls `bash` in [interactive mode][] (`-i`) so that the command can see\n [environment variables][] (`$STENO_DICTIONARIES` in this case) outside of the\n Plover environment\n- gets `bash` to use the [`osascript`][] command-line tool to load in and run\n the target compiled AppleScript ([`.scpt`][] file)\n\nRunning AppleScripts is generally _slow_, and constantly running one-off\ncommands that traverse a stack of `Python->Shell->osascript` made them _even\nslower_.\n\nSo, this plugin leverages [PyXA][] to talk directly to Apple's APIs from Python,\nand keeps a local cache of loaded scripts to avoid needing to re-read in\nAppleScript files every time a command is run.\n\nThe above command now looks like this:\n\n```json\n\"W-D\": \"{:COMMAND:APPLESCRIPT:$STENO_DICTIONARIES/src/command/text/move-one-word-forward.scpt}\"\n```\n\nThe result is that commands at least _feel_ like they run significantly faster,\nand I'm pretty sure it's because they actually are (but I don't have any hard\nbenchmarks to objectively prove this).\n\n## Development\n\nClone from GitHub with [git][]:\n\n```console\ngit clone git@github.com:paulfioravanti/plover-run-applescript.git\ncd plover-run-applescript\n```\n\n### Python Version\n\nPlover's Python environment currently uses version 3.9 (see Plover's\n[`workflow_context.yml`][] to confirm the current version).\n\nSo, in order to avoid unexpected issues, use your runtime version manager to\nmake sure your local development environment also uses Python 3.9.x.\n\n### PyXA Version\n\nThis plugin depends on [PyXA][] for all Python-to-AppleScript interoperations.\nThe dependency is currently pinned at [version 0.0.9][] due to later versions\nof PyXA using Python 3.10 syntax ([`match case`][] etc) that is too new for\nPlover's Python version, and causes syntax errors.\n\n### Testing\n\n- [Pytest][] is used for testing in this plugin.\n- [Coverage.py][] and [pytest-cov][] are used for test coverage, and to run\n coverage within Pytest\n- [Pylint][] is used for code quality\n- [Mypy][] is used for static type checking\n\nCurrently, the only parts able to be tested are ones that do not rely directly\non Plover or PyXA.\n\nRun tests, coverage, and linting with the following commands:\n\n```console\npytest --cov --cov-report=term-missing\npylint plover_run_applescript\nmypy plover_run_applescript\n```\n\nTo get a HTML test coverage report:\n\n```console\ncoverage run --module pytest\ncoverage html\nopen htmlcov/index.html\n```\n\nIf you get `ModuleNotFoundError: No module named 'PyXA'` errors, then run the\nfollowing command to get PyXA available in your test environment:\n\n```console\npip install -e \".[test]\"\n```\n\n### Deploying Changes\n\nAfter making any code changes, install the plugin into Plover with the following\ncommand:\n\n```sh\nplover -s plover_plugins install .\n```\n\n> Where `plover` in the command is a reference to your locally installed version\n> of Plover. See the [Invoke Plover from the command line][] page for details on\n> how to create that reference.\n\n[AppleScript]: https://en.wikipedia.org/wiki/AppleScript\n[Build Status image]: https://github.com/paulfioravanti/plover-run-applescript/actions/workflows/ci.yml/badge.svg\n[Build Status url]: https://github.com/paulfioravanti/plover-run-applescript/actions/workflows/ci.yml\n[command]: https://plover.readthedocs.io/en/latest/plugin-dev/commands.html\n[Coverage.py]: https://github.com/nedbat/coveragepy\n[environment variables]: https://en.wikipedia.org/wiki/Environment_variable\n[extension]: https://plover.readthedocs.io/en/latest/plugin-dev/extensions.html\n[git]: https://git-scm.com/\n[interactive mode]: https://www.gnu.org/software/bash/manual/html_node/Interactive-Shell-Behavior.html\n[Invoke Plover from the command line]: https://github.com/openstenoproject/plover/wiki/Invoke-Plover-from-the-command-line\n[issue with PyXA]: https://github.com/SKaplanOfficial/PyXA/issues/16\n[linting image]: https://img.shields.io/badge/linting-pylint-yellowgreen\n[linting url]: https://github.com/pylint-dev/pylint\n[macOS]: https://en.wikipedia.org/wiki/MacOS\n[`match case`]: https://peps.python.org/pep-0636/\n[my Plover dictionaries]: https://github.com/paulfioravanti/steno-dictionaries/tree/main\n[Mypy]: https://github.com/python/mypy\n[`osacompile`]: https://ss64.com/osx/osacompile.html\n[`osascript`]: https://ss64.com/osx/osascript.html\n[Plover]: https://www.openstenoproject.org/\n[Plover Run Shell]: https://github.com/user202729/plover_run_shell\n[plugin]: https://plover.readthedocs.io/en/latest/plugins.html#types-of-plugins\n[Pylint]: https://github.com/pylint-dev/pylint\n[PyPI downloads image]:https://img.shields.io/pypi/dm/plover-run-applescript\n[PyPI version image]: https://img.shields.io/pypi/v/plover-run-applescript\n[PyPI url]: https://pypi.org/project/plover-run-applescript/\n[Pytest]: https://pytest.org/\n[pytest-cov]: https://github.com/pytest-dev/pytest-cov/\n[PyXA]: https://github.com/SKaplanOfficial/PyXA\n[`.scpt`]: https://fileinfo.com/extension/scpt\n[script libraries]: https://developer.apple.com/library/archive/documentation/LanguagesUtilities/Conceptual/MacAutomationScriptingGuide/UseScriptLibraries.html\n[Sharing AppleScript Handlers]: https://www.paulfioravanti.com/blog/sharing-applescript-handlers/\n[version 0.0.9]: https://github.com/SKaplanOfficial/PyXA/tree/v0.0.9\n[`workflow_context.yml`]: https://github.com/openstenoproject/plover/blob/master/.github/workflows/ci/workflow_context.yml\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 or later (GPLv3+)",
"summary": "Run AppleScripts from Plover",
"version": "0.3.4",
"project_urls": {
"Homepage": "https://github.com/paulfioravanti/plover-run-applescript"
},
"split_keywords": [
"plover",
"plover_plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b732b2eb49c5d25a147629d64e3fcc726b9c4f6ba23926edd018a275518dc554",
"md5": "1494f594617ef02f2e4f840dcfa7d922",
"sha256": "b5f8dd9a0728f97b973b34279d6fcf4a659d7115fb2df1c183130717a1debd3c"
},
"downloads": -1,
"filename": "plover_run_applescript-0.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1494f594617ef02f2e4f840dcfa7d922",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 23090,
"upload_time": "2024-02-10T23:49:52",
"upload_time_iso_8601": "2024-02-10T23:49:52.206805Z",
"url": "https://files.pythonhosted.org/packages/b7/32/b2eb49c5d25a147629d64e3fcc726b9c4f6ba23926edd018a275518dc554/plover_run_applescript-0.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e9f3884a34b17d88aeab63fe532a6eb2b1dcd1f024e2d32de8f74b3a89a1dd63",
"md5": "02092bcf5c074e777bcf870b3ecb2af0",
"sha256": "3210a4bd1013aba5fdd5842a93538afc833a1e5f9c9d5c7f1ef6047f49f15d5c"
},
"downloads": -1,
"filename": "plover_run_applescript-0.3.4.tar.gz",
"has_sig": false,
"md5_digest": "02092bcf5c074e777bcf870b3ecb2af0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 23866,
"upload_time": "2024-02-10T23:49:53",
"upload_time_iso_8601": "2024-02-10T23:49:53.808061Z",
"url": "https://files.pythonhosted.org/packages/e9/f3/884a34b17d88aeab63fe532a6eb2b1dcd1f024e2d32de8f74b3a89a1dd63/plover_run_applescript-0.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-10 23:49:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "paulfioravanti",
"github_project": "plover-run-applescript",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "plover-run-applescript"
}
JSON
