ED/EDMarketConnector
1
0
Fork 0
mirror of https://github.com/EDCD/EDMarketConnector.git synced 2025-06-20 08:44:07 +03:00
Code Issues Projects Releases Wiki Activity

cleaned up plugins.md

Browse Source
This commit is contained in:
A_D 2020-09-18 08:03:07 +02:00
parent a1ae87ed39
commit 4ecb378b83
No known key found for this signature in database
GPG Key ID: 4BE9EB7DF45076C4
1 changed files with 93 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
PLUGINS.md
View File

@ -3,6 +3,7 @@
Plugins allow you to customise and extend the behavior of EDMC. Plugins allow you to customise and extend the behavior of EDMC.
## Installing a Plugin ## Installing a Plugin
See [Plugins](https://github.com/EDCD/EDMarketConnector/wiki/Plugins) on the See [Plugins](https://github.com/EDCD/EDMarketConnector/wiki/Plugins) on the
wiki. wiki.
@ -12,16 +13,16 @@ Plugins are loaded when EDMC starts up.
Each plugin has it's own folder in the `plugins` directory: Each plugin has it's own folder in the `plugins` directory:
* Windows: `%LOCALAPPDATA%\EDMarketConnector\plugins` - Windows: `%LOCALAPPDATA%\EDMarketConnector\plugins`
* Mac: `~/Library/Application Support/EDMarketConnector/plugins` - Mac: `~/Library/Application Support/EDMarketConnector/plugins`
* Linux: `$XDG_DATA_HOME/EDMarketConnector/plugins`, or - Linux: `$XDG_DATA_HOME/EDMarketConnector/plugins`, or `~/.local/share/EDMarketConnector/plugins` if `$XDG_DATA_HOME` is unset.
`~/.local/share/EDMarketConnector/plugins` if `$XDG_DATA_HOME` is unset.
Plugins are python files. The plugin folder must have a file named `load.py` Plugins are python files. The plugin folder must have a file named `load.py`
that must provide one module level function and optionally provide a few that must provide one module level function and optionally provide a few
others. others.
--- ---
### Available imports ### Available imports
**`import`ing anything from the core EDMarketConnector code that is not **`import`ing anything from the core EDMarketConnector code that is not
@ -39,11 +40,11 @@ breaking with future code changes.**
`from prefs import prefsVersion` - to allow for versioned preferences. `from prefs import prefsVersion` - to allow for versioned preferences.
`from companion import category_map` - Or any of the other static date `from companion import category_map` - Or any of the other static date
contained therein. NB: There's a plan to move such to a `data` module. contained therein. NB: There's a plan to move such to a `data` module.
`import plug` - Mostly for using `plug.show_error()`. Also the flags `import plug` - Mostly for using `plug.show_error()`. Also the flags
for `dashboard_entry()` to be useful (see example below). Relying on anything for `dashboard_entry()` to be useful (see example below). Relying on anything
else isn't supported. else isn't supported.
`from monitor import gamerunning` - in case a plugin needs to know if we `from monitor import gamerunning` - in case a plugin needs to know if we
think the game is running. think the game is running.
@ -51,15 +52,17 @@ breaking with future code changes.**
`import timeout_session` - provides a method called `new_session` that creates a requests.session with a default timeout `import timeout_session` - provides a method called `new_session` that creates a requests.session with a default timeout
on all requests. Recommended to reduce noise in HTTP requests on all requests. Recommended to reduce noise in HTTP requests
```python ```python
from ttkHyperlinkLabel import HyperlinkLabel from ttkHyperlinkLabel import HyperlinkLabel
import myNotebook as nb import myNotebook as nb
``` ```
For creating UI elements. For creating UI elements.
--- ---
### Logging ### Logging
In the past the only way to provide any logged output from a In the past the only way to provide any logged output from a
plugin was to use `print(...)` statements. When running the application from plugin was to use `print(...)` statements. When running the application from
the packaged executeable all output is redirected to a log file. See the packaged executeable all output is redirected to a log file. See
@ -72,6 +75,7 @@ statements.
Insert this at the top-level of your load.py file (so not inside Insert this at the top-level of your load.py file (so not inside
`plugin_start3()` ): `plugin_start3()` ):
```python ```python
import logging import logging
@ -149,7 +153,9 @@ functions, in the output.
``` ```
--- ---
### Startup ### Startup
EDMC will import the `load.py` file as a module and then call the EDMC will import the `load.py` file as a module and then call the
`plugin_start3()` function. `plugin_start3()` function.
@ -161,6 +167,7 @@ def plugin_start3(plugin_dir):
print("I am loaded! My plugin folder is {}".format(plugin_dir)) print("I am loaded! My plugin folder is {}".format(plugin_dir))
return "Test" return "Test"
``` ```
The string you return is used as the internal name of the plugin. The string you return is used as the internal name of the plugin.
Any errors or print statements from your plugin will appear in Any errors or print statements from your plugin will appear in
@ -168,6 +175,7 @@ Any errors or print statements from your plugin will appear in
Mac, and `$TMP/EDMarketConnector.log` on Linux. Mac, and `$TMP/EDMarketConnector.log` on Linux.
### Shutdown ### Shutdown
This gets called when the user closes the program: This gets called when the user closes the program:
```python ```python
@ -182,6 +190,7 @@ If your plugin uses one or more threads to handle Events then stop and join()
the threads before returning from this function. the threads before returning from this function.
## Plugin Hooks ## Plugin Hooks
### Configuration ### Configuration
If you want your plugin to be configurable via the GUI you can define a frame If you want your plugin to be configurable via the GUI you can define a frame
@ -335,8 +344,7 @@ This gets called when EDMC sees a new entry in the game's journal.
- `Manufactured` - `dict` with details of "Manufactured" materials held. - `Manufactured` - `dict` with details of "Manufactured" materials held.
- `Encoded` - `dict` with details of "Encoded" materials held. - `Encoded` - `dict` with details of "Encoded" materials held.
- `Engineers` - `dict` with details of Rank Progress for Engineers. - `Engineers` - `dict` with details of Rank Progress for Engineers.
- `Rank` - `dict` of current Ranks. Each entry is a `tuple` of - `Rank` - `dict` of current Ranks. Each entry is a 2 `tuple` of ints, rank and age
(<rank `int`>, <progress %age `int`>)
- `Reputation` - `dict` of Major Faction reputations, scale is -100 to +100 - `Reputation` - `dict` of Major Faction reputations, scale is -100 to +100
See Frontier's Journal Manual for detail of bands. See Frontier's Journal Manual for detail of bands.
- `Statistics` - `dict` of a Journal "Statistics" event, i.e. data shown - `Statistics` - `dict` of a Journal "Statistics" event, i.e. data shown
@ -366,7 +374,6 @@ Similarly, a special "ShutDown" entry is sent when the game is quitted while
EDMC is running. This event is not sent when EDMC is running on a different EDMC is running. This event is not sent when EDMC is running on a different
machine so you should not *rely* on receiving this event. machine so you should not *rely* on receiving this event.
#### Player Dashboard #### Player Dashboard
```python ```python
@ -380,7 +387,6 @@ def dashboard_entry(cmdr, is_beta, entry):
This gets called when something on the player's cockpit display changes - This gets called when something on the player's cockpit display changes -
typically about once a second when in orbital flight. typically about once a second when in orbital flight.
- `cmdr` is a `str` denoting the current Commander Name. - `cmdr` is a `str` denoting the current Commander Name.
- `is_beta` is a `bool` denoting if data came from a beta version of the game. - `is_beta` is a `bool` denoting if data came from a beta version of the game.
- `entry` is a `dict` loaded from the Status.json file the game writes. - `entry` is a `dict` loaded from the Status.json file the game writes.
@ -389,6 +395,7 @@ typically about once a second when in orbital flight.
Ask on the EDCD Discord server to be sure you have the latest version. Ask on the EDCD Discord server to be sure you have the latest version.
Refer to the source code of [plug.py](./plug.py) for the list of available Refer to the source code of [plug.py](./plug.py) for the list of available
constants. constants.
#### Getting Commander Data #### Getting Commander Data
```python ```python
@ -405,7 +412,7 @@ Frontier's servers.
- `data` is a dictionary containing the response from Frontier to a CAPI - `data` is a dictionary containing the response from Frontier to a CAPI
`/profile` request, augmented with two extra keys: `/profile` request, augmented with two extra keys:
- `marketdata` - contains the CAPI data from the `/market` endpoint, if - `marketdata` - contains the CAPI data from the `/market` endpoint, if
docked and the station has the commodites service. docked and the station has the commodities service.
- `shipdata` - contains the CAPI data from the `/shipyard` endpoint, if - `shipdata` - contains the CAPI data from the `/shipyard` endpoint, if
docked and the station has the shipyard service. docked and the station has the shipyard service.
- `is_beta` is a `bool` denoting if data came from a beta version of the game. - `is_beta` is a `bool` denoting if data came from a beta version of the game.
@ -432,21 +439,24 @@ called when the player starts the game or enters a new system. It is called
some time after the corresponding `journal_entry()` event. some time after the corresponding `journal_entry()` event.
--- ---
```python ```python
def inara_notify_location(eventData): def inara_notify_location(eventData):
""" """
`eventData` holds the response to one of the "Commander's Flight Log" events https://inara.cz/inara-api-docs/#event-29 `eventData` holds the response to one of the "Commander's Flight Log" events https://inara.cz/inara-api-docs/#event-29
""" """
if eventData.get('starsystemInaraID'): if eventData.get('starsystemInaraID'):
sys.stderr.write('Now in Inara system {ID} at {URL}\n'.format(ID=eventData['starsystemInaraID'], sys.stderr.write('Now in Inara system {ID} at {URL}\n'.format(
URL=eventData['starsystemInaraURL']) ID=eventData['starsystemInaraID'],
) URL=eventData['starsystemInaraURL']
))
else: else:
sys.stderr.write('System not known to Inara\n') sys.stderr.write('System not known to Inara\n')
if eventData.get('stationInaraID'): if eventData.get('stationInaraID'):
sys.stderr.write('Docked at Inara station {ID} at {URL}\n'.format(ID=eventData['stationInaraID'], sys.stderr.write('Docked at Inara station {ID} at {URL}\n'.format(
URL=eventData['stationInaraURL']) ID=eventData['stationInaraID'],
) URL=eventData['stationInaraURL']
))
else: else:
sys.stderr.write('Undocked or station unknown to Inara\n') sys.stderr.write('Undocked or station unknown to Inara\n')
``` ```
@ -457,15 +467,17 @@ undocks. It is called some time after the corresponding `journal_entry()`
event. event.
--- ---
```python ```python
def inara_notify_ship(eventData): def inara_notify_ship(eventData):
""" """
`eventData` holds the response to an addCommanderShip or setCommanderShip event https://inara.cz/inara-api-docs/#event-11 `eventData` holds the response to an addCommanderShip or setCommanderShip event https://inara.cz/inara-api-docs/#event-11
""" """
if eventData.get('shipInaraID'): if eventData.get('shipInaraID'):
sys.stderr.write('Now in Inara ship {ID} at {URL}\n'.format(ID=eventData['shipInaraID'], sys.stderr.write('Now in Inara ship {ID} at {URL}\n'.format(
URL=eventData['shipInaraURL']) ID=eventData['shipInaraID'],
) URL=eventData['shipInaraURL']
))
``` ```
If the player has chosen to "Send flight log and Cmdr status to Inara" this If the player has chosen to "Send flight log and Cmdr status to Inara" this
@ -517,7 +529,6 @@ See EDMC's own [`L10n`](https://github.com/EDCD/EDMarketConnector/tree/master/L1
folder for the list of supported language codes and for example translation folder for the list of supported language codes and for example translation
files. files.
## Python Package Plugins ## Python Package Plugins
A _Package Plugin_ is both a standard Python package (i.e. contains an A _Package Plugin_ is both a standard Python package (i.e. contains an
@ -528,15 +539,14 @@ before any non-Package plugins.
Other plugins can access features in a Package Plugin by `import`ing the Other plugins can access features in a Package Plugin by `import`ing the
package by name in the usual way. package by name in the usual way.
## Distributing a Plugin ## Distributing a Plugin
To package your plugin for distribution simply create a `.zip` archive of your To package your plugin for distribution simply create a `.zip` archive of your
plugin's folder: plugin's folder:
* Windows: In Explorer right click on your plugin's folder and choose Send to - Windows: In Explorer right click on your plugin's folder and choose Send to
&rarr; Compressed (zipped) folder. &rarr; Compressed (zipped) folder.
* Mac: In Finder right click on your plugin's folder and choose Compress. - Mac: In Finder right click on your plugin's folder and choose Compress.
If there are any external dependencies then include them in the plugin's If there are any external dependencies then include them in the plugin's
folder. folder.
@ -562,15 +572,18 @@ required to migrate a plugin from earlier versions of EDMC:
"Plugins" tab and a message like "plugin SuperSpaceHelper needs migrating" "Plugins" tab and a message like "plugin SuperSpaceHelper needs migrating"
appears in the log. Such plugins are also listed in a section "Plugins Without appears in the log. Such plugins are also listed in a section "Plugins Without
Python 3.x Support:" on the Settings > Plugins tab. Python 3.x Support:" on the Settings > Plugins tab.
- Check that callback functions `plugin_prefs`, `prefs_changed`, - Check that callback functions `plugin_prefs`, `prefs_changed`,
`journal_entry`, `dashboard_entry` and `cmdr_data` if used are declared with `journal_entry`, `dashboard_entry` and `cmdr_data` if used are declared with
the correct number of arguments. Older versions of this app were tolerant the correct number of arguments. Older versions of this app were tolerant
of missing arguments in these function declarations. of missing arguments in these function declarations.
- Port the code to Python 3.7. The [2to3](https://docs.python.org/3/library/2to3.html) - Port the code to Python 3.7. The [2to3](https://docs.python.org/3/library/2to3.html)
tool can automate much of this work. tool can automate much of this work.
Depending on the complexity of the plugin it may be feasible to make it Depending on the complexity of the plugin it may be feasible to make it
compatible with both EDMC 3.4 + Python 2.7 and EDMC 3.5 + Python 3.7. compatible with both EDMC 3.4 + Python 2.7 and EDMC 3.5 + Python 3.7.
[Here's](https://python-future.org/compatible_idioms.html) a guide on writing [Here's](https://python-future.org/compatible_idioms.html) a guide on writing
Python 2/3 compatible code and [here's](https://github.com/Marginal/HabZone/commit/3c41cd41d5ad81ef36aab40e967e3baf77b4bd06) Python 2/3 compatible code and [here's](https://github.com/Marginal/HabZone/commit/3c41cd41d5ad81ef36aab40e967e3baf77b4bd06)
an example of the changes required for a simple plugin. an example of the changes required for a simple plugin.