ED/EDMarketConnector
1
0
Fork 0
mirror of https://github.com/EDCD/EDMarketConnector.git synced 2025-06-19 16:24: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.
## Installing a Plugin
See [Plugins](https://github.com/EDCD/EDMarketConnector/wiki/Plugins) on the
wiki.
@ -12,16 +13,16 @@ Plugins are loaded when EDMC starts up.
Each plugin has it's own folder in the `plugins` directory:
* Windows: `%LOCALAPPDATA%\EDMarketConnector\plugins`
* Mac: `~/Library/Application Support/EDMarketConnector/plugins`
* Linux: `$XDG_DATA_HOME/EDMarketConnector/plugins`, or
`~/.local/share/EDMarketConnector/plugins` if `$XDG_DATA_HOME` is unset.
- Windows: `%LOCALAPPDATA%\EDMarketConnector\plugins`
- Mac: `~/Library/Application Support/EDMarketConnector/plugins`
- Linux: `$XDG_DATA_HOME/EDMarketConnector/plugins`, or `~/.local/share/EDMarketConnector/plugins` if `$XDG_DATA_HOME` is unset.
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
others.
---
### Available imports
**`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 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
for `dashboard_entry()` to be useful (see example below). Relying on anything
else isn't supported.
for `dashboard_entry()` to be useful (see example below). Relying on anything
else isn't supported.
`from monitor import gamerunning` - in case a plugin needs to know if we
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
on all requests. Recommended to reduce noise in HTTP requests
```python
from ttkHyperlinkLabel import HyperlinkLabel
import myNotebook as nb
```
For creating UI elements.
---
### Logging
In the past the only way to provide any logged output from a
plugin was to use `print(...)` statements. When running the application from
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
`plugin_start3()` ):
```python
import logging
@ -149,7 +153,9 @@ functions, in the output.
```
---
### Startup
EDMC will import the `load.py` file as a module and then call the
`plugin_start3()` function.
@ -161,6 +167,7 @@ def plugin_start3(plugin_dir):
print("I am loaded! My plugin folder is {}".format(plugin_dir))
return "Test"
```
The string you return is used as the internal name of the plugin.
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.
### Shutdown
This gets called when the user closes the program:
```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.
## Plugin Hooks
### Configuration
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.
- `Encoded` - `dict` with details of "Encoded" materials held.
- `Engineers` - `dict` with details of Rank Progress for Engineers.
- `Rank` - `dict` of current Ranks. Each entry is a `tuple` of
(<rank `int`>, <progress %age `int`>)
- `Rank` - `dict` of current Ranks. Each entry is a 2 `tuple` of ints, rank and age
- `Reputation` - `dict` of Major Faction reputations, scale is -100 to +100
See Frontier's Journal Manual for detail of bands.
- `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
machine so you should not *rely* on receiving this event.
#### Player Dashboard
```python
@ -380,7 +387,6 @@ def dashboard_entry(cmdr, is_beta, entry):
This gets called when something on the player's cockpit display changes -
typically about once a second when in orbital flight.
- `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.
- `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.
Refer to the source code of [plug.py](./plug.py) for the list of available
constants.
#### Getting Commander Data
```python
@ -405,7 +412,7 @@ Frontier's servers.
- `data` is a dictionary containing the response from Frontier to a CAPI
`/profile` request, augmented with two extra keys:
- `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
docked and the station has the shipyard service.
- `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.
---
```python
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
"""
if eventData.get('starsystemInaraID'):
sys.stderr.write('Now in Inara system {ID} at {URL}\n'.format(ID=eventData['starsystemInaraID'],
URL=eventData['starsystemInaraURL'])
)
sys.stderr.write('Now in Inara system {ID} at {URL}\n'.format(
ID=eventData['starsystemInaraID'],
URL=eventData['starsystemInaraURL']
))
else:
sys.stderr.write('System not known to Inara\n')
if eventData.get('stationInaraID'):
sys.stderr.write('Docked at Inara station {ID} at {URL}\n'.format(ID=eventData['stationInaraID'],
URL=eventData['stationInaraURL'])
)
sys.stderr.write('Docked at Inara station {ID} at {URL}\n'.format(
ID=eventData['stationInaraID'],
URL=eventData['stationInaraURL']
))
else:
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.
---
```python
def inara_notify_ship(eventData):
"""
`eventData` holds the response to an addCommanderShip or setCommanderShip event https://inara.cz/inara-api-docs/#event-11
"""
if eventData.get('shipInaraID'):
sys.stderr.write('Now in Inara ship {ID} at {URL}\n'.format(ID=eventData['shipInaraID'],
URL=eventData['shipInaraURL'])
)
sys.stderr.write('Now in Inara ship {ID} at {URL}\n'.format(
ID=eventData['shipInaraID'],
URL=eventData['shipInaraURL']
))
```
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
files.
## Python Package Plugins
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
package by name in the usual way.
## Distributing a Plugin
To package your plugin for distribution simply create a `.zip` archive of your
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.
* 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
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"
appears in the log. Such plugins are also listed in a section "Plugins Without
Python 3.x Support:" on the Settings > Plugins tab.
- Check that callback functions `plugin_prefs`, `prefs_changed`,
`journal_entry`, `dashboard_entry` and `cmdr_data` if used are declared with
the correct number of arguments. Older versions of this app were tolerant
of missing arguments in these function declarations.
- Port the code to Python 3.7. The [2to3](https://docs.python.org/3/library/2to3.html)
tool can automate much of this work.
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.
[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)
an example of the changes required for a simple plugin.