From 71bb14a7377749a95a7831f83ff2e3981a9e503b Mon Sep 17 00:00:00 2001
From: Athanasius <github@miggy.org>
Date: Sun, 12 Jul 2020 19:25:47 +0100
Subject: [PATCH] Document allowed imports for PLUGINS

* List added in 'Available imports' section of PLUGINS.md
* Various *.py files now have comments about things being allowed for
 plugin import.
---
 PLUGINS.md           | 28 +++++++++++++++++++++++++++-
 companion.py         |  2 +-
 config.py            |  2 +-
 myNotebook.py        |  1 +
 prefs.py             |  2 +-
 ttkHyperlinkLabel.py |  1 +
 6 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/PLUGINS.md b/PLUGINS.md
index 64c3d0c7..7768cf6e 100644
--- a/PLUGINS.md
+++ b/PLUGINS.md
@@ -21,6 +21,32 @@ 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
+explicitly mentioned here is unsupported and may lead to your plugin
+breaking with future code changes.**
+
+`from config import appname, applongname, appcmdname, appversion
+, copyright, config` - to access config.
+
+`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.
+
+`import plug` - Mostly for using `plug.show_error()`.  Relying on anything
+ else isn't supported.
+
+```python
+from ttkHyperlinkLabel import HyperlinkLabel
+import myNotebook as nb
+```
+For creating UI elements.
+
+
+---
 ### Startup
 EDMC will import the `load.py` file as a module and then call the
 `plugin_start3()` function.
@@ -282,7 +308,7 @@ Frontier's servers.
      docked and the station has the shipyard service.
 - `is_beta` is a `bool` denoting if data came from a beta version of the game.
 
-#### Plugin-specific events.
+#### Plugin-specific events
 
 ```python
 def edsm_notify_system(reply):
diff --git a/companion.py b/companion.py
index f6496125..57911342 100644
--- a/companion.py
+++ b/companion.py
@@ -48,7 +48,7 @@ URL_SHIPYARD= '/shipyard'
 
 
 # Map values reported by the Companion interface to names displayed in-game
-
+# May be imported by plugins
 category_map = {
     'Narcotics'     : 'Legal Drugs',
     'Slaves'        : 'Slavery',
diff --git a/config.py b/config.py
index eb8266df..7f97fa60 100644
--- a/config.py
+++ b/config.py
@@ -4,7 +4,7 @@ from os import getenv, makedirs, mkdir, pardir
 from os.path import expanduser, dirname, exists, isdir, join, normpath
 from sys import platform
 
-
+# Any of these may be imported by plugins
 appname = 'EDMarketConnector'
 applongname = 'E:D Market Connector'
 appcmdname = 'EDMC'
diff --git a/myNotebook.py b/myNotebook.py
index d42cae17..19f2aaa6 100644
--- a/myNotebook.py
+++ b/myNotebook.py
@@ -10,6 +10,7 @@ from sys import platform
 import tkinter as tk
 from tkinter import ttk
 
+# Entire file may be imported by plugins
 
 # Can't do this with styles on OSX - http://www.tkdocs.com/tutorial/styles.html#whydifficult
 if platform == 'darwin':
diff --git a/prefs.py b/prefs.py
index d3dbe139..e381eb45 100644
--- a/prefs.py
+++ b/prefs.py
@@ -23,7 +23,7 @@ import plug
 # 'new' preferences, or not.
 ###########################################################################
 
-
+# May be imported by plugins
 class PrefsVersion(object):
     versions = {
         '0.0.0.0': 1,
diff --git a/ttkHyperlinkLabel.py b/ttkHyperlinkLabel.py
index a04a8b3b..627a987f 100644
--- a/ttkHyperlinkLabel.py
+++ b/ttkHyperlinkLabel.py
@@ -18,6 +18,7 @@ if platform == 'win32':
 #   underline: If True/False the text is always/never underlined. If None (the default) the text is underlined only on hover.
 #   popup_copy: Whether right-click on non-empty label text pops up a context menu with a 'Copy' option. Defaults to no context menu. If popup_copy is a function it will be called with the current label text and should return a boolean.
 #
+# May be imported by plugins
 class HyperlinkLabel(platform == 'darwin' and tk.Label or ttk.Label, object):
 
     def __init__(self, master=None, **kw):