# plover-python-dictionary-lib
Library for writing Python dictionary for Plover,
and generating JSON dictionary file from Python dictionary.
A Python dictionary is a Plover dictionary that is written in Python.
Refer to [documentation of the `plover-python-dictionary` package](https://pypi.org/project/plover-python-dictionary/)
to see what is the advantage of a Python dictionary.
This library provides some convenient helper tools to write a dictionary.
### Installation
This package is available on
[PyPI](https://pypi.org/project/plover-python-dictionary-lib/).
To install it, run the command
```bash
pip install plover-python-dictionary-lib
```
This is required to use/run the Python dictionaries that use this library.
### Example & Usage
#### Getting started
This is a minimal example of a Python dictionary. You can save it as `helloworld.py` and load it into Plover, provided
`plover-python-dictionary` package is installed.
```python
#!/bin/python3
from plover.system import english_stenotype as e
from plover_python_dictionary_lib import get_context_from_system
context=get_context_from_system(e)
s=context.SingleDictionary
stroke=context.stroke
translation=context.translation
dictionary=s({
"S": "hello world"
})
lookup = lambda strokes: dictionary.lookup_tuple(strokes)
LONGEST_KEY = dictionary.longest_key
if __name__=="__main__":
dictionary.print_items()
```
When loaded into Plover, it will define a dictionary with a single translation, as suggested by the `dictionary` variable.
It can also be run as a standalone Python script to print out the JSON dictionary it would corresponds to.
Refer to ["Generate JSON" section](#generate-json) for details.
#### Dictionary Operations
The power of the package comes from the variety of built-in functions that allows manipulating the components easily
to build up a whole dictionary.
When you have built up the desired dictionary, simply assign it to the `dictionary` variable, and set `lookup` and `LONGEST_KEY` correspondingly.
You can experiment with the operators simply by running the necessary imports in a Python shell;
alternatively, just run the Python file standalone to print out the content of the dictionary.
* The `|` operator
* Compute the union of two dictionaries together (basically updating one dictionary with another as like a normal python dictionary)
```python
you = s({"KPWR": "you"})
they = s({"TWH": "they"})
dict1 = you | they
dict1.print_items()
# {"KPWR": "you", "TWH": "they"}
```
* The `*` operator
* Compute the Cartesian product of two dictionaries such that:
* Adjacent strokes are merged as according to steno order
* Adjacent translations are merged using the `+` operator
* Example:
```python
dict1 = s({
"KPWR": "you",
"TWH": "they"
})
dict2 = s({
"-R": " are"
})
dict = dict1 * dict2
dict.print_items()
# {"KPWR-R": "you are", "TWH-R": "they are"}
```
#### `map()` method
Allows you to modify the content of an existing dictionary.
```python
>>> dict1 = s({"S": "is", "K": "can"})
>>> dict1.map(lambda x: x*2)
MappedDictionary({(S,): 'isis', (K,): 'cancan'})
```
You can also map over the keys provided the arguments are specially named as `strokes` and `result`:
```python
>>> dict1.map(lambda strokes, result: f"{result} ({strokes})")
MappedDictionary({(S,): 'is ((S,))', (K,): 'can ((K,))'})
```
You can also customize the argument names:
```python
def applyMods(mods, characters):
for mod in mods:
characters = f"{mod}({characters})"
return characters
mods = s({"-R": ["shift"], "": []}).named("mods")
characters = s({"A": "a"}).named("characters")
dict = (mods * characters).map(applyMods)
dict.print_items()
# {"AR": "shift(a)", "A": "a"}
```
In this case, `named("characters")` marks that the translation of the `characters` dictionary is
to be passed to the argument named `characters` in `applyMods`.
#### Extra
* You can read
* [`00_two_letter_fingerspelling_example` example dictionary file](https://github.com/user202729/plover-python-dictionary-lib/blob/main/example/00_two_letter_fingerspelling_example.py) (GitHub link) for an example (this one is the most well-documented example file, with common patterns and explanation),
* the rest of the files in the [`example/` folder](https://github.com/user202729/plover-python-dictionary-lib/tree/main/example),
* and the documentation (as Python docstrings) in the source code,
* Useful resources: [Frequently used dictionary components](https://github.com/user202729/plover-python-dictionary-lib/wiki/Frequently-used-dictionary-components) *(feel free to edit the wiki)*
### Generate JSON
The Python dictionary must be written with this plugin.
Call `.print_items()` on the main `Dictionary` object. (see also the example dictionaries above)
For example: if this code
is included at the end of the Python dictionary file named `dictionary.py`
```python
if __name__=="__main__":
dictionary.print_items()
```
(assuming that the main dictionary object is named `dictionary`) then running `python dictionary.py`
will print the dictionary as JSON to the standard output.
**Note**: If you get the error:
```
ModuleNotFoundError: No module named 'plover'
```
it means Plover was installed in a different Python *environment* from the environment that you ran the script in.
It depends on the operating-system and specific installation method how to run it in the correct environment. See https://github.com/user202729/plover-python-dictionary-lib/issues/4 for an example.
**Note** (fixed bug, affects old version only): because of [an incompatibility between Plover and the `plover_stroke` library](https://github.com/benoit-pierre/plover_stroke/issues/1),
sometimes the JSON dictionary may not work in Plover.
Raw data
{
"_id": null,
"home_page": "https://github.com/user202729/plover-python-dictionary-lib",
"name": "plover-python-dictionary-lib",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "plover",
"author": "user202729",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/b9/f5/fabf56846f55c1b915a648b55ede1e84168a1faf60ab187d77f42424fe99/plover_python_dictionary_lib-0.4.4.tar.gz",
"platform": null,
"description": "# plover-python-dictionary-lib\nLibrary for writing Python dictionary for Plover,\nand generating JSON dictionary file from Python dictionary.\n\nA Python dictionary is a Plover dictionary that is written in Python.\nRefer to [documentation of the `plover-python-dictionary` package](https://pypi.org/project/plover-python-dictionary/)\nto see what is the advantage of a Python dictionary.\n\nThis library provides some convenient helper tools to write a dictionary.\n\n### Installation\n\nThis package is available on \n[PyPI](https://pypi.org/project/plover-python-dictionary-lib/).\nTo install it, run the command\n\n```bash\npip install plover-python-dictionary-lib\n```\n\nThis is required to use/run the Python dictionaries that use this library.\n\n### Example & Usage\n\n#### Getting started\n\nThis is a minimal example of a Python dictionary. You can save it as `helloworld.py` and load it into Plover, provided\n`plover-python-dictionary` package is installed.\n\n```python\n#!/bin/python3\nfrom plover.system import english_stenotype as e\nfrom plover_python_dictionary_lib import get_context_from_system\ncontext=get_context_from_system(e)\ns=context.SingleDictionary\nstroke=context.stroke\ntranslation=context.translation\n\ndictionary=s({\n\t\"S\": \"hello world\"\n\t})\n\nlookup = lambda strokes: dictionary.lookup_tuple(strokes)\nLONGEST_KEY = dictionary.longest_key\n\nif __name__==\"__main__\":\n\tdictionary.print_items()\n```\n\nWhen loaded into Plover, it will define a dictionary with a single translation, as suggested by the `dictionary` variable.\n\nIt can also be run as a standalone Python script to print out the JSON dictionary it would corresponds to.\nRefer to [\"Generate JSON\" section](#generate-json) for details.\n\n#### Dictionary Operations\n\nThe power of the package comes from the variety of built-in functions that allows manipulating the components easily\nto build up a whole dictionary.\n\nWhen you have built up the desired dictionary, simply assign it to the `dictionary` variable, and set `lookup` and `LONGEST_KEY` correspondingly.\n\nYou can experiment with the operators simply by running the necessary imports in a Python shell;\nalternatively, just run the Python file standalone to print out the content of the dictionary.\n\n* The `|` operator\n\t* Compute the union of two dictionaries together (basically updating one dictionary with another as like a normal python dictionary)\n```python\nyou = s({\"KPWR\": \"you\"})\nthey = s({\"TWH\": \"they\"})\ndict1 = you | they\ndict1.print_items()\n# {\"KPWR\": \"you\", \"TWH\": \"they\"}\n```\n\n* The `*` operator\n\t* Compute the Cartesian product of two dictionaries such that:\n\t\t* Adjacent strokes are merged as according to steno order\n\t\t* Adjacent translations are merged using the `+` operator\n\t* Example:\n```python\ndict1 = s({\n\t\t\"KPWR\": \"you\",\n\t\t\"TWH\": \"they\"\n\t})\ndict2 = s({\n\t\t\"-R\": \" are\"\n\t})\ndict = dict1 * dict2\ndict.print_items()\n# {\"KPWR-R\": \"you are\", \"TWH-R\": \"they are\"}\n```\n\n#### `map()` method\n\nAllows you to modify the content of an existing dictionary.\n```python\n>>> dict1 = s({\"S\": \"is\", \"K\": \"can\"})\n>>> dict1.map(lambda x: x*2)\nMappedDictionary({(S,): 'isis', (K,): 'cancan'})\n```\n\nYou can also map over the keys provided the arguments are specially named as `strokes` and `result`:\n```python\n>>> dict1.map(lambda strokes, result: f\"{result} ({strokes})\")\nMappedDictionary({(S,): 'is ((S,))', (K,): 'can ((K,))'})\n```\n\nYou can also customize the argument names:\n\n```python\ndef applyMods(mods, characters):\n\tfor mod in mods:\n\t\tcharacters = f\"{mod}({characters})\"\n\treturn characters\nmods = s({\"-R\": [\"shift\"], \"\": []}).named(\"mods\") \ncharacters = s({\"A\": \"a\"}).named(\"characters\")\ndict = (mods * characters).map(applyMods)\ndict.print_items()\n# {\"AR\": \"shift(a)\", \"A\": \"a\"}\n```\nIn this case, `named(\"characters\")` marks that the translation of the `characters` dictionary is\nto be passed to the argument named `characters` in `applyMods`.\n\n#### Extra\n\n* You can read\n\t* [`00_two_letter_fingerspelling_example` example dictionary file](https://github.com/user202729/plover-python-dictionary-lib/blob/main/example/00_two_letter_fingerspelling_example.py) (GitHub link) for an example (this one is the most well-documented example file, with common patterns and explanation),\n\t* the rest of the files in the [`example/` folder](https://github.com/user202729/plover-python-dictionary-lib/tree/main/example),\n\t* and the documentation (as Python docstrings) in the source code,\n* Useful resources: [Frequently used dictionary components](https://github.com/user202729/plover-python-dictionary-lib/wiki/Frequently-used-dictionary-components) *(feel free to edit the wiki)*\n\n### Generate JSON\n\nThe Python dictionary must be written with this plugin.\n\nCall `.print_items()` on the main `Dictionary` object. (see also the example dictionaries above)\n\n\nFor example: if this code\nis included at the end of the Python dictionary file named `dictionary.py`\n\n```python\nif __name__==\"__main__\":\n\tdictionary.print_items()\n```\n\n(assuming that the main dictionary object is named `dictionary`) then running `python dictionary.py`\nwill print the dictionary as JSON to the standard output.\n\n**Note**: If you get the error:\n```\nModuleNotFoundError: No module named 'plover'\n```\nit means Plover was installed in a different Python *environment* from the environment that you ran the script in.\n\nIt depends on the operating-system and specific installation method how to run it in the correct environment. See https://github.com/user202729/plover-python-dictionary-lib/issues/4 for an example.\n\n**Note** (fixed bug, affects old version only): because of [an incompatibility between Plover and the `plover_stroke` library](https://github.com/benoit-pierre/plover_stroke/issues/1),\nsometimes the JSON dictionary may not work in Plover.\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 or later (GPLv3+)",
"summary": "Library for writing Python dictionary for Plover, and generating JSON dictionary file from Python dictionary.",
"version": "0.4.4",
"project_urls": {
"Homepage": "https://github.com/user202729/plover-python-dictionary-lib"
},
"split_keywords": [
"plover"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6912589cc2e630ff28b8b90f415c444be130ed33918a38c31869c5c9bec29e37",
"md5": "d33671de776c0b2a71a37ae747444a14",
"sha256": "4aca55522e8d53e076af7402fa8d8aeb4882719316a7a3d400db0e76617e17df"
},
"downloads": -1,
"filename": "plover_python_dictionary_lib-0.4.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d33671de776c0b2a71a37ae747444a14",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 30215,
"upload_time": "2024-01-27T09:02:36",
"upload_time_iso_8601": "2024-01-27T09:02:36.426545Z",
"url": "https://files.pythonhosted.org/packages/69/12/589cc2e630ff28b8b90f415c444be130ed33918a38c31869c5c9bec29e37/plover_python_dictionary_lib-0.4.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b9f5fabf56846f55c1b915a648b55ede1e84168a1faf60ab187d77f42424fe99",
"md5": "938baf05baca64163773bfce5348b6d3",
"sha256": "8ca30d911b0fe5abc68e141acdd34fdc16f1e26e37e0dff00090d8b3f9f88d19"
},
"downloads": -1,
"filename": "plover_python_dictionary_lib-0.4.4.tar.gz",
"has_sig": false,
"md5_digest": "938baf05baca64163773bfce5348b6d3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 27374,
"upload_time": "2024-01-27T09:02:38",
"upload_time_iso_8601": "2024-01-27T09:02:38.583615Z",
"url": "https://files.pythonhosted.org/packages/b9/f5/fabf56846f55c1b915a648b55ede1e84168a1faf60ab187d77f42424fe99/plover_python_dictionary_lib-0.4.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-27 09:02:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "user202729",
"github_project": "plover-python-dictionary-lib",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "plover-python-dictionary-lib"
}
JSON
