ED/EDMarketConnector
1
0
Fork 0
mirror of https://github.com/EDCD/EDMarketConnector.git synced 2025-04-15 00:30:33 +03:00
Code Issues Projects Releases Wiki Activity

Revert unnoticed whitespace modifications to PLUGINS.py

Browse Source
This commit is contained in:
aussig 2022-12-23 13:01:47 +00:00
parent 7e726e606a
commit 3c8eca16af
1 changed files with 47 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
PLUGINS.md
View File

@ -31,7 +31,7 @@ then you'll need to be using an appropriate version of Python. The current
version is listed in the version is listed in the
[Environment section of Releasing.md](https://github.com/EDCD/EDMarketConnector/blob/main/docs/Releasing.md#environment). [Environment section of Releasing.md](https://github.com/EDCD/EDMarketConnector/blob/main/docs/Releasing.md#environment).
If you're developing your plugin simply against an install of EDMarketConnector If you're developing your plugin simply against an install of EDMarketConnector
then you'll be relying on the bundled version of Python (it's baked then you'll be relying on the bundled version of Python (it's baked
into the .exe via the py2exe build process). into the .exe via the py2exe build process).
Please be sure to read the [Avoiding potential pitfalls](#avoiding-potential-pitfalls) Please be sure to read the [Avoiding potential pitfalls](#avoiding-potential-pitfalls)
@ -40,21 +40,21 @@ EDMarketConnector code including whole application crashes.
## Being aware of core application changes ## Being aware of core application changes
It is highly advisable to ensure you are aware of all EDMarketConnector It is highly advisable to ensure you are aware of all EDMarketConnector
releases, including the pre-releases. The -beta and -rc changelogs will releases, including the pre-releases. The -beta and -rc changelogs will
contain valuable information about any forthcoming changes that affect plugins. contain valuable information about any forthcoming changes that affect plugins.
The easiest way is: The easiest way is:
1. Login to [GitHub](https://github.com). 1. Login to [GitHub](https://github.com).
2. Navigate to [EDMarketConnector](https://github.com/EDCD/EDMarketConnector). 2. Navigate to [EDMarketConnector](https://github.com/EDCD/EDMarketConnector).
3. Click the 'Watch' (or 'Unwatch' if you previously set up any watches on 3. Click the 'Watch' (or 'Unwatch' if you previously set up any watches on
us). It's currently (2021-05-13) the left-most button of 3 near the us). It's currently (2021-05-13) the left-most button of 3 near the
top-right of the page. top-right of the page.
4. Click 'Custom'. 4. Click 'Custom'.
5. Ensure 'Releases' is selected. 5. Ensure 'Releases' is selected.
6. Click 'Apply'. 6. Click 'Apply'.
And, of course, either ensure you check your GitHub messages regularly, or And, of course, either ensure you check your GitHub messages regularly, or
have it set up to email you such notifications. have it set up to email you such notifications.
You should also keep an eye on [our GitHub Discussions](https://github.com/EDCD/EDMarketConnector/discussions) You should also keep an eye on [our GitHub Discussions](https://github.com/EDCD/EDMarketConnector/discussions)
@ -113,13 +113,13 @@ from the original files unless specified as allowed in this section.
Use `monitor.game_running()` as follows in case a plugin needs to know if we Use `monitor.game_running()` as follows in case a plugin needs to know if we
think the game is running. *NB: This is a function, and should be called as think the game is running. *NB: This is a function, and should be called as
such. Using the bare word `game_running` will always be `True`.* such. Using the bare word `game_running` will always be `True`.*
``` ```
from monitor import monitor from monitor import monitor
... ...
if monitor.game_running(): if monitor.game_running():
... ...
``` ```
`import timeout_session` - provides a method called `new_session` that creates `import timeout_session` - provides a method called `new_session` that creates
a requests.session with a default timeout on all requests. Recommended to a requests.session with a default timeout on all requests. Recommended to
@ -128,7 +128,7 @@ reduce noise in HTTP requests
`from ttkHyperlinkLabel import HyperlinkLabel` and `import myNotebook as nb` - `from ttkHyperlinkLabel import HyperlinkLabel` and `import myNotebook as nb` -
For creating UI elements. For creating UI elements.
In addition to the above we also explicitly package the following python In addition to the above we also explicitly package the following python
modules for plugin use: modules for plugin use:
- shutil - shutil
@ -245,7 +245,7 @@ include variables, and even the returns of functions, in the output.
## Checking core EDMC version ## Checking core EDMC version
If you have code that needs to act differently under different versions of If you have code that needs to act differently under different versions of
this application then you can check utilise `config.appversion`. this application then you can check utilise `config.appversion`.
Prior to version 5.0.0 this was a simple string. From 5.0.0 onwards it is, Prior to version 5.0.0 this was a simple string. From 5.0.0 onwards it is,
@ -306,7 +306,7 @@ Mac, and `$TMP/EDMarketConnector.log` on Linux.
## Avoiding potential pitfalls ## Avoiding potential pitfalls
There are a number of things that your code should either do or avoiding There are a number of things that your code should either do or avoiding
doing so as to play nicely with the core EDMarketConnector code and not risk doing so as to play nicely with the core EDMarketConnector code and not risk
causing application crashes or hangs. causing application crashes or hangs.
@ -317,12 +317,12 @@ See the section on [packaging extra modules](#your-plugin-directory-name-must-be
### Use a thread for long-running code ### Use a thread for long-running code
By default, your plugin code will be running in the main thread. So, if you By default, your plugin code will be running in the main thread. So, if you
perform some operation that takes significant time (more than a second) you perform some operation that takes significant time (more than a second) you
will be blocking both the core code from continuing *and* any other plugins will be blocking both the core code from continuing *and* any other plugins
from running their main-thread code. from running their main-thread code.
This includes any connections to remote services, such as a website or This includes any connections to remote services, such as a website or
remote database. So please place such code within its own thread. remote database. So please place such code within its own thread.
See the [EDSM plugin](https://github.com/EDCD/EDMarketConnector/blob/main/plugins/edsm.py) See the [EDSM plugin](https://github.com/EDCD/EDMarketConnector/blob/main/plugins/edsm.py)
@ -331,20 +331,20 @@ with a queue to send data, and telling the sub-thread to stop during shutdown.
### All tkinter calls in main thread ### All tkinter calls in main thread
The only tkinter calls that should ever be made from a sub-thread are The only tkinter calls that should ever be made from a sub-thread are
`event_generate()` calls to send data back to the main thread. `event_generate()` calls to send data back to the main thread.
Any attempt to manipulate tkinter UI elements directly from a sub-thread Any attempt to manipulate tkinter UI elements directly from a sub-thread
will most likely crash the whole program. will most likely crash the whole program.
See the [EDSM plugin](https://github.com/EDCD/EDMarketConnector/blob/main/plugins/edsm.py) See the [EDSM plugin](https://github.com/EDCD/EDMarketConnector/blob/main/plugins/edsm.py)
code for an example of using `event_generate()` to cause the plugin main code for an example of using `event_generate()` to cause the plugin main
thread code to update a UI element. Start from the `plugin_app()` thread code to update a UI element. Start from the `plugin_app()`
implementation. implementation.
### Do not call tkinter `event_generate` during shutdown. ### Do not call tkinter `event_generate` during shutdown.
However, you must **not** make *any* tkinter `event_generate()` call whilst However, you must **not** make *any* tkinter `event_generate()` call whilst
the application is shutting down. the application is shutting down.
The application shutdown sequence is itself triggered from the `<<Quit>>` event The application shutdown sequence is itself triggered from the `<<Quit>>` event
@ -352,8 +352,8 @@ handler, and generating another event from any code in, or called from,
there causes the application to hang somewhere in the tk libraries. there causes the application to hang somewhere in the tk libraries.
You can detect if the application is shutting down with the boolean You can detect if the application is shutting down with the boolean
`config.shutting_down`. Note that although this is technically a function `config.shutting_down`. Note that although this is technically a function
its implementation is of a property on `config.AbstractConfig` and thus you its implementation is of a property on `config.AbstractConfig` and thus you
should treat it as a variable. should treat it as a variable.
**Do NOT use**: **Do NOT use**:
@ -365,7 +365,7 @@ should treat it as a variable.
# During shutdown # During shutdown
``` ```
as this will cause the 'During shutdown' branch to *always* be taken, as in as this will cause the 'During shutdown' branch to *always* be taken, as in
this context you're testing if the function exists, and that is always True. this context you're testing if the function exists, and that is always True.
So instead use: So instead use:
@ -396,8 +396,8 @@ your plugin's settings in a platform-independent way. Previously this was done
with a single set and two get methods, the new methods provide better type with a single set and two get methods, the new methods provide better type
safety. safety.
If you want to maintain compatibility with pre-5.0.0 versions of this If you want to maintain compatibility with pre-5.0.0 versions of this
application (please encourage plugin users to update!) then you'll need to application (please encourage plugin users to update!) then you'll need to
include this code in at least once in your plugin (no harm in putting it in include this code in at least once in your plugin (no harm in putting it in
all modules/files): all modules/files):
@ -670,8 +670,8 @@ cause `state['NavRoute'] = None`, but if you open the galaxy map in-game and
cause an automatic re-plot of last route, then a new `NavRoute` event will cause an automatic re-plot of last route, then a new `NavRoute` event will
also be generated and passed to plugins. also be generated and passed to plugins.
[2] - Some data from the CAPI is sometimes returned as a `list` (when all [2] - Some data from the CAPI is sometimes returned as a `list` (when all
members are present) and other times as an integer-keyed `dict` (when at members are present) and other times as an integer-keyed `dict` (when at
least one member is missing, so the indices are not contiguous). We choose to least one member is missing, so the indices are not contiguous). We choose to
always convert to the integer-keyed `dict` form so that code utilising the data always convert to the integer-keyed `dict` form so that code utilising the data
is simpler. is simpler.
@ -697,7 +697,7 @@ Journal `ModuleInfo` event.
`OnFoot` is an indication as to if the player is on-foot, rather than in a `OnFoot` is an indication as to if the player is on-foot, rather than in a
vehicle. vehicle.
`Component`, `Item`, `Consumable` & `Data` are `dict`s tracking your `Component`, `Item`, `Consumable` & `Data` are `dict`s tracking your
Odyssey MicroResources in your Ship Locker. `BacKPack` contains `dict`s for Odyssey MicroResources in your Ship Locker. `BacKPack` contains `dict`s for
the same when you're on-foot. the same when you're on-foot.
@ -706,10 +706,10 @@ relating to suits and their loadouts.
New in version 5.0.1: New in version 5.0.1:
`Odyssey` boolean based on the presence of such a flag in the `LoadGame` `Odyssey` boolean based on the presence of such a flag in the `LoadGame`
event. Defaults to `False`, i.e. if no such key in the event. event. Defaults to `False`, i.e. if no such key in the event.
The previously undocumented `Horizons` boolean is similarly from `LoadGame`, The previously undocumented `Horizons` boolean is similarly from `LoadGame`,
but blindly retrieves the value rather than having a strict default. There'd but blindly retrieves the value rather than having a strict default. There'd
be an exception if it wasn't there, and the value would be `None`. Note that be an exception if it wasn't there, and the value would be `None`. Note that
this is **NOT** the same as the return from this is **NOT** the same as the return from
@ -786,8 +786,8 @@ react to either in your plugin code then either compare in a case insensitive
manner or check for both. The difference in case allows you to differentiate manner or check for both. The difference in case allows you to differentiate
between the two scenarios. between the two scenarios.
**NB: Any of these events are passing to `journal_entry_cqc` rather than to **NB: Any of these events are passing to `journal_entry_cqc` rather than to
`journal_entry` if player has loaded into Arena (CQC).** `journal_entry` if player has loaded into Arena (CQC).**
This event is not sent when EDMarketConnector is running on a different This event is not sent when EDMarketConnector 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.
@ -804,15 +804,15 @@ Examples of this are:
1. Every `NavRoute` event contains the full `Route` array as loaded from 1. Every `NavRoute` event contains the full `Route` array as loaded from
`NavRoute.json`. `NavRoute.json`.
*NB: There is no indication available when a player cancels a route.* The *NB: There is no indication available when a player cancels a route.* The
game itself does not provide any such, not in a Journal event, not in a game itself does not provide any such, not in a Journal event, not in a
`Status.json` flag. `Status.json` flag.
The Journal documentation v28 is incorrect about the event The Journal documentation v28 is incorrect about the event
and file being `Route(.json)` the word is `NavRoute`. Also the format of and file being `Route(.json)` the word is `NavRoute`. Also the format of
the data is, e.g. the data is, e.g.
```json ```json
{ "timestamp":"2021-03-10T11:31:37Z", { "timestamp":"2021-03-10T11:31:37Z",
"event":"NavRoute", "event":"NavRoute",
@ -826,9 +826,9 @@ Examples of this are:
``` ```
1. Every `ModuleInfo` event contains the full data as loaded from the 1. Every `ModuleInfo` event contains the full data as loaded from the
`ModulesInfo.json` file. Note that we use the singular form here to `ModulesInfo.json` file. Note that we use the singular form here to
stay consistent with the Journal event name. stay consistent with the Journal event name.
--- ---
### Journal entry in CQC ### Journal entry in CQC
@ -888,7 +888,7 @@ def dashboard_entry(cmdr: str, is_beta: bool, entry: Dict[str, Any]):
sys.stderr.write("Hardpoints {}\n".format(is_deployed and "deployed" or "stowed")) sys.stderr.write("Hardpoints {}\n".format(is_deployed and "deployed" or "stowed"))
``` ```
`dashboard_entry()` is called with the latest data from the `Status.json` `dashboard_entry()` is called with the latest data from the `Status.json`
file when an update to that file is detected. file when an update to that file is detected.
This will be when something on the player's cockpit display changes - This will be when something on the player's cockpit display changes -
@ -985,10 +985,7 @@ will always be the case**.
In the `capi_fleetcarrier()` callback, the contents of `data` will be the response from the CAPI `/fleetcarrier` query. See [this documentation](https://github.com/Athanasius/fd-api/blob/main/docs/FrontierDevelopments-CAPI-endpoints.md) for details of the expected content structure and data. In the `capi_fleetcarrier()` callback, the contents of `data` will be the response from the CAPI `/fleetcarrier` query. See [this documentation](https://github.com/Athanasius/fd-api/blob/main/docs/FrontierDevelopments-CAPI-endpoints.md) for details of the expected content structure and data.
In all cases, `data` will include a `request_cmdr` entry, which will be the In all cases, `data` will include a `request_cmdr` entry, which will be the name of the active CMDR _at the point the request was made_. In the case of a CAPI request taking a long time to return, the user may have switched CMDR during the request, so this may be different to the current CMDR.
name of the active CMDR _at the point the request was made_. In the case of
a CAPI request taking a long time to return, the user may have switched
CMDR during the request, so this may be different to the current CMDR.
If there is a killswitch in effect for some of the CAPI endpoints, then the If there is a killswitch in effect for some of the CAPI endpoints, then the
data passed to this function might not be as complete as you expect. Code data passed to this function might not be as complete as you expect. Code
@ -1202,11 +1199,11 @@ Any modules the core application code uses will naturally be packaged, and
we explicitly include a small number of additional modules for the use of we explicitly include a small number of additional modules for the use of
plugins. plugins.
Whilst we would like to make all of the `stdlib` of Python available it is Whilst we would like to make all of the `stdlib` of Python available it is
not automatically packaged into our releases by py2exe. We hope to address not automatically packaged into our releases by py2exe. We hope to address
this in the 5.3 release series. In the meantime, if there's anything this in the 5.3 release series. In the meantime, if there's anything
missing that you'd like to use, please ask. Yes, this very much means you missing that you'd like to use, please ask. Yes, this very much means you
need to test your plugins against a Windows installation of the application need to test your plugins against a Windows installation of the application
to be sure it will work. to be sure it will work.
See See
@ -1356,7 +1353,7 @@ versions of EDMarketConnector:
[2to3](https://docs.python.org/3/library/2to3.html) [2to3](https://docs.python.org/3/library/2to3.html)
tool can automate much of this work. tool can automate much of this work.
We advise *against* making any attempt to have a plugin's code work under We advise *against* making any attempt to have a plugin's code work under
both Python 2.7 and 3.x. We no longer maintain the Python 2.7-based both Python 2.7 and 3.x. We no longer maintain the Python 2.7-based
versions of this application, and you shouldn't support use of them with versions of this application, and you shouldn't support use of them with
your plugin. your plugin.