plover-platform-specific-translation 0.2.5

Description:

ploverplatformspecifictranslation 0.2.5

Plover Platform Specific Translation

This Plover extension plugin contains a meta that allows you to
specify different outline translation values depending on what operating system
(platform) you are using.
This can be helpful in times where if you use the same dictionaries with Plover
across, say, Windows and macOS, and want to have a single outline for "copy" to
translate as Control-C on Windows, but Command-C on macOS.
Install
Pre-Plover Plugin Registry inclusion (Current)
git clone [email protected]:paulfioravanti/plover-platform-specific-translation.git
cd plover-platform-specific-translation
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.

Then:

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_platform_specific_translation to activate the
plugin

Post-Plover Plugin Registry inclusion (Future)

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-platform-specific-translation
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_platform_specific_translation to activate the
plugin

How To Use
Using the example of an outline for "copy", here are the different ways you can
create a platform-specific translation in your steno dictionaries.
Specify a translation for all possible (and unknown) platforms:
"KP*EU": "{:PLATFORM:WINDOWS:#CONTROL(C):MAC:#SUPER(C):LINUX:#CONTROL(C):OTHER:#CONTROL(C)}"

Specify a translation for only some platforms, and provide a default fallback
translation for any other platform:
"KP*EU": "{:PLATFORM:MAC:#SUPER(C):OTHER:#CONTROL(C)}"

Specify a translation for only some platforms, but without a fallback for other
platforms (will show an error if current platform is not found, but if you are
confident you know what platforms you work with, this should be fine):
"KP*EU": "{:PLATFORM:WINDOWS:#CONTROL(C):MAC:#SUPER(C)}"

Specify only a default fallback for other platforms (pointless, but supported):
"KP*EU": "{:PLATFORM:OTHER:#CONTROL(C)}"

Note that the translation values are not limited to keyboard shortcuts, and can
contain commands to run:
"TO*LG": "{:PLATFORM:WINDOWS:PLOVER:TOGGLE_DICT:+win_dict.py:MAC::COMMAND:TOGGLE_DICT:+mac_dict.py}"


Both command prefixes of {PLOVER:<command>} and {:COMMAND:<command>} are
supported.

Naturally, plain text output is also supported:
"H-L": "{:PLATFORM:WINDOWS:Hello:MAC:Hi:LINUX:Good day:OTHER:Whassup}"

Configuration
When a platform-specific translation is successfully determined from an outline,
the result is stored in the local Plover configuration directory on your
machine in a file called platform_specific_translation.json. This is done in
order to prevent determination actions from being done multiple times for the
same outline, and hence speed up lookups for already known translations.
You should not need to manually add any entries to the configuration, but if you
find any obsolete entries, feel free to delete them.
Technical Details
The heart of this plugin is essentially Python's platform.system()
function, which will tell you what operating system you are running Plover on.
It will return one of the following values:

"Windows"
"Darwin" (macOS)
"Linux"
"Java" (this looks like a value for potentially deprecated Jython
environments, in which Plover will very likely never run in, so it is not
supported in this plugin)
"" (unknown platform)

When the extension starts, the value returned from platform.system() gets
cached to avoid checking it every time an outline is stroked.
All the platform-specific translations also get cached, so subsequent stroking
of outlines that contain them should feel snappier than the first time they are
used.
Pressing the "Disconnect and reconnect the machine" button on the Plover UI
resets the translation cache. If you make any changes to a specific
platform-specific translation in an outline, make sure to press it so it can
be re-read in again properly.
Development
Clone from GitHub with git:
git clone [email protected]:paulfioravanti/plover-platform-specific-translation.git
cd plover-platform-specific-translation
python -m pip install --editable ".[test]"

If you are a Tmuxinator user, you may find my
plover_platform_specific_translation 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.
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.
Run tests, coverage, and linting with the following commands:
pytest --cov --cov-report=term-missing
pylint plover_local_env_var
mypy plover_local_env_var

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, deploy 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-platform-specific-translation