# Plover Platform Specific Translation
[![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 [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
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-platform-specific-translation`
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_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:
```json
"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:
```json
"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):
```json
"KP*EU": "{:PLATFORM:WINDOWS:#CONTROL(C),MAC:#SUPER(C)}"
```
Specify only a default fallback for other platforms (pointless, but supported):
```json
"KP*EU": "{:PLATFORM:OTHER:#CONTROL(C)}"
```
Note that the translation values are not limited to keyboard shortcuts, and can
contain [commands][] to run:
```json
"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:
```json
"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][]:
```console
git clone git@github.com: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:
```console
pytest --cov --cov-report=term-missing
pylint plover_local_env_var
mypy plover_local_env_var
```
To get a HTML test coverage report:
```console
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:
```console
just --working-directory . --justfile test/justfile
```
### Deploying Changes
After making any code changes, deploy the plugin into Plover with the following
command:
```console
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:
```console
plover --script plover_plugins uninstall plover-platform-specific-translation
```
[Build Status image]: https://github.com/paulfioravanti/plover-platform-specific-translation/actions/workflows/ci.yml/badge.svg
[Build Status url]: https://github.com/paulfioravanti/plover-platform-specific-translation/actions/workflows/ci.yml
[commands]: https://plover.readthedocs.io/en/latest/plugin-dev/commands.html
[Coverage.py]: https://github.com/nedbat/coveragepy
[extension]: https://plover.readthedocs.io/en/latest/plugin-dev/extensions.html
[git]: https://git-scm.com/
[Invoke Plover from the command line]: https://github.com/openstenoproject/plover/wiki/Invoke-Plover-from-the-command-line
[`just`]: https://github.com/casey/just
[`justfile`]: ./test/justfile
[Jython]: https://www.jython.org/
[linting image]: https://img.shields.io/badge/linting-pylint-yellowgreen
[linting url]: https://github.com/pylint-dev/pylint
[meta]: https://plover.readthedocs.io/en/latest/plugin-dev/metas.html
[my steno dictionaries]: https://github.com/paulfioravanti/steno-dictionaries
[Mypy]: https://github.com/python/mypy
[`platform.system()`]: https://docs.python.org/3/library/platform.html#platform.system
[Plover]: https://www.openstenoproject.org/
[Plover configuration directory]: https://plover.readthedocs.io/en/latest/api/oslayer_config.html#plover.oslayer.config.CONFIG_DIR
[plover_platform_specific_translation project file]: https://github.com/paulfioravanti/dotfiles/blob/master/tmuxinator/plover_platform_specific_translation.yml
[plugin]: https://plover.readthedocs.io/en/latest/plugins.html#types-of-plugins
[potentially deprecated]: https://discuss.python.org/t/lets-deprecate-platform-system-java/48026/4
[Pylint]: https://github.com/pylint-dev/pylint
[PyPI downloads image]:https://img.shields.io/pypi/dm/plover-platform-specific-translation
[PyPI version image]: https://img.shields.io/pypi/v/plover-platform-specific-translation
[PyPI url]: https://pypi.org/project/plover-platform-specific-translation/
[Pytest]: https://pytest.org/
[pytest-cov]: https://github.com/pytest-dev/pytest-cov/
[Python]: https://www.python.org/
[Tmuxinator]: https://github.com/tmuxinator/tmuxinator
[`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-platform-specific-translation",
"name": "plover-platform-specific-translation",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "plover plover_plugin",
"author": "Paul Fioravanti",
"author_email": "paul@paulfioravanti.com",
"download_url": "https://files.pythonhosted.org/packages/11/39/795258cb079741eaa92a4f3baf1da0c5432606683311252c2ab3fa53547f/plover_platform_specific_translation-0.3.0.tar.gz",
"platform": null,
"description": "# Plover Platform Specific Translation\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 [meta][] that allows you to\nspecify different outline translation values depending on what operating system\n(platform) you are using.\n\nThis can be helpful in times where if you use the same dictionaries with Plover\nacross, say, Windows and macOS, and want to have a single outline for \"copy\" to\ntranslate as Control-C on Windows, but Command-C on macOS.\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-platform-specific-translation`\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_platform_specific_translation` to activate the\n plugin\n\n## How To Use\n\nUsing the example of an outline for \"copy\", here are the different ways you can\ncreate a platform-specific translation in your steno dictionaries.\n\nSpecify a translation for all possible (and unknown) platforms:\n\n```json\n\"KP*EU\": \"{:PLATFORM:WINDOWS:#CONTROL(C),MAC:#SUPER(C),LINUX:#CONTROL(C),OTHER:#CONTROL(C)}\"\n```\n\nSpecify a translation for only some platforms, and provide a default fallback\ntranslation for any other platform:\n\n```json\n\"KP*EU\": \"{:PLATFORM:MAC:#SUPER(C),OTHER:#CONTROL(C)}\"\n```\n\nSpecify a translation for only some platforms, but without a fallback for other\nplatforms (will show an error if current platform is not found, but if you are\nconfident you know what platforms you work with, this should be fine):\n\n```json\n\"KP*EU\": \"{:PLATFORM:WINDOWS:#CONTROL(C),MAC:#SUPER(C)}\"\n```\n\nSpecify only a default fallback for other platforms (pointless, but supported):\n\n```json\n\"KP*EU\": \"{:PLATFORM:OTHER:#CONTROL(C)}\"\n```\n\nNote that the translation values are not limited to keyboard shortcuts, and can\ncontain [commands][] to run:\n\n```json\n\"TO*LG\": \"{:PLATFORM:WINDOWS:PLOVER:TOGGLE_DICT:+win_dict.py,MAC::COMMAND:TOGGLE_DICT:+mac_dict.py}\"\n```\n\n> Both command prefixes of `{PLOVER:<command>}` and `{:COMMAND:<command>}` are\n> supported.\n\nNaturally, plain text output is also supported:\n\n```json\n\"H-L\": \"{:PLATFORM:WINDOWS:Hello,MAC:Hi,LINUX:Good day,OTHER:Whassup}\"\n```\n\n## Configuration\n\nWhen a platform-specific translation is successfully determined from an outline,\nthe result is stored in the local [Plover configuration directory][] on your\nmachine in a file called `platform_specific_translation.json`. This is done in\norder to prevent determination actions from being done multiple times for the\nsame outline, and hence speed up lookups for already known translations.\n\nYou should not need to manually add any entries to the configuration, but if you\nfind any obsolete entries, feel free to delete them.\n\n## Technical Details\n\nThe heart of this plugin is essentially [Python][]'s [`platform.system()`][]\nfunction, which will tell you what operating system you are running Plover on.\nIt will return one of the following values:\n\n- `\"Windows\"`\n- `\"Darwin\"` (macOS)\n- `\"Linux\"`\n- `\"Java\"` (this looks like a value for [potentially deprecated][] [Jython][]\n environments, in which Plover will very likely never run in, so it is not\n supported in this plugin)\n- `\"\"` (unknown platform)\n\nWhen the extension starts, the value returned from `platform.system()` gets\ncached to avoid checking it every time an outline is stroked.\n\nAll the platform-specific translations also get cached, so subsequent stroking\nof outlines that contain them should feel snappier than the first time they are\nused.\n\nPressing the \"Disconnect and reconnect the machine\" button on the Plover UI\nresets the translation cache. If you make any changes to a specific\nplatform-specific translation in an outline, make sure to press it so it can\nbe re-read in again properly.\n\n## Development\n\nClone from GitHub with [git][]:\n\n```console\ngit clone git@github.com:paulfioravanti/plover-platform-specific-translation.git\ncd plover-platform-specific-translation\npython -m pip install --editable \".[test]\"\n```\n\nIf you are a [Tmuxinator][] user, you may find my\n[plover_platform_specific_translation project file][] of reference.\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### 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.\n\nRun tests, coverage, and linting with the following commands:\n\n```console\npytest --cov --cov-report=term-missing\npylint plover_local_env_var\nmypy plover_local_env_var\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 are a [`just`][] user, you may find the [`justfile`][] useful during\ndevelopment in running multiple test commands. You can run the following command\nfrom the project root directory:\n\n```console\njust --working-directory . --justfile test/justfile\n```\n\n### Deploying Changes\n\nAfter making any code changes, deploy the plugin into Plover with the following\ncommand:\n\n```console\nplover --script plover_plugins install --editable .\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\nWhen necessary, the plugin can be uninstalled via the command line with the\nfollowing command:\n\n```console\nplover --script plover_plugins uninstall plover-platform-specific-translation\n```\n\n[Build Status image]: https://github.com/paulfioravanti/plover-platform-specific-translation/actions/workflows/ci.yml/badge.svg\n[Build Status url]: https://github.com/paulfioravanti/plover-platform-specific-translation/actions/workflows/ci.yml\n[commands]: https://plover.readthedocs.io/en/latest/plugin-dev/commands.html\n[Coverage.py]: https://github.com/nedbat/coveragepy\n[extension]: https://plover.readthedocs.io/en/latest/plugin-dev/extensions.html\n[git]: https://git-scm.com/\n[Invoke Plover from the command line]: https://github.com/openstenoproject/plover/wiki/Invoke-Plover-from-the-command-line\n[`just`]: https://github.com/casey/just\n[`justfile`]: ./test/justfile\n[Jython]: https://www.jython.org/\n[linting image]: https://img.shields.io/badge/linting-pylint-yellowgreen\n[linting url]: https://github.com/pylint-dev/pylint\n[meta]: https://plover.readthedocs.io/en/latest/plugin-dev/metas.html\n[my steno dictionaries]: https://github.com/paulfioravanti/steno-dictionaries\n[Mypy]: https://github.com/python/mypy\n[`platform.system()`]: https://docs.python.org/3/library/platform.html#platform.system\n[Plover]: https://www.openstenoproject.org/\n[Plover configuration directory]: https://plover.readthedocs.io/en/latest/api/oslayer_config.html#plover.oslayer.config.CONFIG_DIR\n[plover_platform_specific_translation project file]: https://github.com/paulfioravanti/dotfiles/blob/master/tmuxinator/plover_platform_specific_translation.yml\n[plugin]: https://plover.readthedocs.io/en/latest/plugins.html#types-of-plugins\n[potentially deprecated]: https://discuss.python.org/t/lets-deprecate-platform-system-java/48026/4\n[Pylint]: https://github.com/pylint-dev/pylint\n[PyPI downloads image]:https://img.shields.io/pypi/dm/plover-platform-specific-translation\n[PyPI version image]: https://img.shields.io/pypi/v/plover-platform-specific-translation\n[PyPI url]: https://pypi.org/project/plover-platform-specific-translation/\n[Pytest]: https://pytest.org/\n[pytest-cov]: https://github.com/pytest-dev/pytest-cov/\n[Python]: https://www.python.org/\n[Tmuxinator]: https://github.com/tmuxinator/tmuxinator\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": "Define multiple platform (OS) specific translations in a single steno outline.",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/paulfioravanti/plover-platform-specific-translation"
},
"split_keywords": [
"plover",
"plover_plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "126309f029e089f3fd2340276b41354ab684d2418c184dd44ba30810a57a1a1b",
"md5": "dfafc3a23dbb8f760aac027d86e81121",
"sha256": "5aa54153f485129dc99bc375865daca815f8ad95a408e7b2e579aa0d5c5e49d7"
},
"downloads": -1,
"filename": "plover_platform_specific_translation-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dfafc3a23dbb8f760aac027d86e81121",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 24018,
"upload_time": "2024-11-06T01:52:13",
"upload_time_iso_8601": "2024-11-06T01:52:13.031921Z",
"url": "https://files.pythonhosted.org/packages/12/63/09f029e089f3fd2340276b41354ab684d2418c184dd44ba30810a57a1a1b/plover_platform_specific_translation-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1139795258cb079741eaa92a4f3baf1da0c5432606683311252c2ab3fa53547f",
"md5": "700c12ec3eb1b8c49cc10c41bd5796b1",
"sha256": "975dc5a605c184c8e85419c52e0dfac589e29c2c3149cc0d5108af80bf47f5c1"
},
"downloads": -1,
"filename": "plover_platform_specific_translation-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "700c12ec3eb1b8c49cc10c41bd5796b1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 23881,
"upload_time": "2024-11-06T01:52:15",
"upload_time_iso_8601": "2024-11-06T01:52:15.032031Z",
"url": "https://files.pythonhosted.org/packages/11/39/795258cb079741eaa92a4f3baf1da0c5432606683311252c2ab3fa53547f/plover_platform_specific_translation-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-06 01:52:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "paulfioravanti",
"github_project": "plover-platform-specific-translation",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "plover-platform-specific-translation"
}
JSON
