0
# Plugin Registry System
1
2
The Plover plugin registry provides centralized management for all extensible components including machines, dictionaries, GUI tools, extensions, and other plugin types. It enables dynamic discovery, registration, and access to plugins throughout the application.
3
4
## Capabilities
5
6
### Registry Management
7
8
Central registry for plugin discovery and management with support for dynamic registration and plugin enumeration.
9
10
```python { .api }
11
class Registry:
12
"""Central plugin registry for all Plover extensions."""
13
14
PLUGIN_TYPES = (
15
'command', 'dictionary', 'extension', 'gui',
16
'gui.qt.machine_option', 'gui.qt.tool', 'machine',
17
'macro', 'meta', 'system'
18
)
19
20
def register_plugin(self, plugin_type: str, name: str, obj) -> None:
21
"""
22
Register a plugin with the registry.
23
24
Args:
25
plugin_type: Type of plugin from PLUGIN_TYPES
26
name: Unique name for the plugin
27
obj: Plugin class or object to register
28
29
Registers plugin for discovery by other components.
30
"""
31
32
def get_plugin(self, plugin_type: str, plugin_name: str) -> Plugin:
33
"""
34
Get specific plugin by type and name.
35
36
Args:
37
plugin_type: Type of plugin to retrieve
38
plugin_name: Name of specific plugin
39
40
Returns:
41
Plugin wrapper object with metadata
42
43
Raises:
44
KeyError: If plugin not found
45
"""
46
47
def list_plugins(self, plugin_type: str) -> list:
48
"""
49
List all plugins of specified type.
50
51
Args:
52
plugin_type: Type of plugins to list
53
54
Returns:
55
List of Plugin objects of specified type
56
57
Useful for enumerating available options like machines or dictionaries.
58
"""
59
60
def list_distributions(self) -> list:
61
"""
62
List all plugin distributions.
63
64
Returns:
65
List of distribution objects containing plugins
66
67
Shows all installed packages that provide plugins.
68
"""
69
70
def update(self) -> None:
71
"""
72
Update registry from entry points.
73
74
Scans installed packages for new plugins and updates
75
the registry with any discoveries.
76
"""
77
```
78
79
### Global Registry Instance
80
81
```python { .api }
82
registry: Registry
83
"""
84
Global registry instance used throughout Plover.
85
86
All components access plugins through this shared instance.
87
"""
88
```
89
90
### Plugin Wrapper
91
92
Individual plugin metadata and access wrapper.
93
94
```python { .api }
95
class Plugin:
96
"""Wrapper for individual plugin with metadata."""
97
98
def __init__(self, plugin_type: str, name: str, obj):
99
"""
100
Initialize plugin wrapper.
101
102
Args:
103
plugin_type: Type classification of plugin
104
name: Unique identifier for plugin
105
obj: Actual plugin class or object
106
"""
107
108
plugin_type: str
109
"""Type classification from Registry.PLUGIN_TYPES"""
110
111
name: str
112
"""Unique plugin identifier"""
113
114
obj: object
115
"""Actual plugin class or implementation object"""
116
117
__doc__: str
118
"""Plugin documentation string"""
119
```
120
121
## Plugin Types
122
123
### Command Plugins ('command')
124
Execute specific stenographic commands or configuration changes.
125
126
**Examples:**
127
- `set_config`: Configuration modification commands
128
129
### Dictionary Plugins ('dictionary')
130
Support different dictionary file formats for stenographic translations.
131
132
**Examples:**
133
- `json`: JSON dictionary format support
134
- `rtf`: RTF/CRE dictionary format support
135
136
### Extension Plugins ('extension')
137
Background extensions that enhance Plover functionality.
138
139
**Examples:**
140
- Custom automation extensions
141
- Integration with external applications
142
- Workflow enhancement tools
143
144
### GUI Plugins ('gui')
145
Main GUI interface implementations.
146
147
**Examples:**
148
- `none`: Headless operation mode
149
- `qt`: Qt-based graphical interface
150
151
### GUI Machine Option Plugins ('gui.qt.machine_option')
152
Machine-specific configuration dialogs for the Qt GUI.
153
154
### GUI Tool Plugins ('gui.qt.tool')
155
Specialized tools and windows within the Qt GUI.
156
157
**Examples:**
158
- `add_translation`: Translation addition tool
159
- `lookup`: Dictionary lookup tool
160
- `paper_tape`: Stroke display tool
161
- `suggestions`: Suggestion display tool
162
163
### Machine Plugins ('machine')
164
Stenotype machine drivers for hardware communication.
165
166
**Examples:**
167
- `Gemini PR`: Gemini PR protocol machine
168
- `Keyboard`: Computer keyboard input
169
- `Passport`: Passport stenotype machine
170
- `ProCAT`: ProCAT stenotype machine
171
- `Stentura`: Stentura stenotype machine
172
- `TX Bolt`: TX Bolt protocol machine
173
174
### Macro Plugins ('macro')
175
Automated stroke sequences and text manipulation macros.
176
177
**Examples:**
178
- `repeat_last_stroke`: Repeat previous stroke
179
- `retro_delete_space`: Delete preceding space
180
- `retro_insert_space`: Insert space before text
181
- `retro_toggle_asterisk`: Toggle asterisk in previous stroke
182
- `undo`: Undo previous translation
183
184
### Meta Plugins ('meta')
185
Text formatting and output manipulation commands.
186
187
**Examples:**
188
- `attach`: Control text attachment
189
- `case`: Case formatting control
190
- `carry_capitalize`: Capitalization carry-forward
191
- `comma`: Comma insertion with formatting
192
- `command`: Execute system commands
193
- `glue`: Text gluing without spaces
194
- `key_combo`: Send key combinations
195
- `mode`: Mode switching control
196
- `retro_case`: Retroactive case changes
197
- `retro_currency`: Currency formatting
198
- `stop`: Stop translation processing
199
- `word_end`: Word ending control
200
201
### System Plugins ('system')
202
Stenotype system definitions with key layouts and rules.
203
204
**Examples:**
205
- `English Stenotype`: Standard English stenotype system
206
207
## Usage Examples
208
209
```python
210
from plover.registry import registry
211
212
# Update registry from installed packages
213
registry.update()
214
215
# List available machines
216
machines = registry.list_plugins('machine')
217
for machine in machines:
218
print(f"Machine: {machine.name}")
219
220
# Get specific machine plugin
221
gemini_plugin = registry.get_plugin('machine', 'Gemini PR')
222
gemini_machine = gemini_plugin.obj
223
224
# List all GUI tools
225
tools = registry.list_plugins('gui.qt.tool')
226
for tool in tools:
227
print(f"Tool: {tool.name} - {tool.__doc__}")
228
229
# Register custom plugin
230
class CustomExtension:
231
def __init__(self, engine):
232
self.engine = engine
233
234
def start(self):
235
pass
236
237
def stop(self):
238
pass
239
240
registry.register_plugin('extension', 'my_extension', CustomExtension)
241
242
# List dictionary formats
243
dict_formats = registry.list_plugins('dictionary')
244
for fmt in dict_formats:
245
print(f"Dictionary format: {fmt.name}")
246
247
# Get meta command
248
attach_meta = registry.get_plugin('meta', 'attach')
249
attach_command = attach_meta.obj
250
```
251
252
## Plugin Development
253
254
### Plugin Entry Points
255
256
Plugins are registered through Python entry points in `setup.py` or `pyproject.toml`:
257
258
```python
259
# setup.py
260
entry_points={
261
'plover.machine': [
262
'My Machine = my_package.machine:MyMachine',
263
],
264
'plover.extension': [
265
'My Extension = my_package.extension:MyExtension',
266
],
267
'plover.dictionary': [
268
'My Format = my_package.dictionary:MyDictionary',
269
],
270
}
271
```
272
273
### Plugin Discovery
274
275
The registry automatically discovers plugins through:
276
277
1. **Entry Points**: Scans `pkg_resources` entry points for plugin types
278
2. **Distribution Scanning**: Examines installed packages for Plover plugins
279
3. **Dynamic Registration**: Allows runtime plugin registration
280
281
### Plugin Interface Requirements
282
283
Each plugin type has specific interface requirements:
284
285
- **Machine plugins**: Must inherit from `StenotypeBase`
286
- **Dictionary plugins**: Must inherit from `StenoDictionary`
287
- **Extension plugins**: Must implement `__init__(engine)`, `start()`, `stop()`
288
- **GUI tool plugins**: Must inherit from `Tool` base class
289
- **Meta plugins**: Must be callable functions taking translation arguments
290
291
## Types
292
293
```python { .api }
294
from typing import List, Dict, Any, Callable, Type, Union
295
296
PluginType = str
297
PluginName = str
298
PluginObject = Union[Type, Callable, object]
299
300
PluginTypesList = tuple[str, ...]
301
PluginsList = List[Plugin]
302
DistributionsList = List[Any]
303
```