Add documentation for relative plugin imports

diff --git a/PLUGINS.md b/PLUGINS.md
index 6fd20ef9..71aaec7a 100644
--- a/PLUGINS.md
+++ b/PLUGINS.md
@@ -163,6 +163,19 @@ circular imports.
 For an example of how this is done, look at the code in `plugins/common_coreutils.py`
 and the usage of these functions in other core plugins.

+Plugins may import additional code modules from `load.py` in the usual way. Note
+that using an import statement like `import my_module` or `from my_module import
+foo` will only import one module with that name **across all plugins**. This can
+be used to create a shared library used by several plugins if used carefully,
+but may create a conflict if another plugin also has a module of the same name
+containing different code. For example if two plugins both contain a
+`widgets.py` file and both do `import widgets`, only one of the two modules will
+actually be imported.
+
+To avoid this issue, use a relative import statement such as `import .widgets`
+or `from .widgets import foo` to ensure that the module is loaded from the
+current plugin, even if the name conflicts with another plugin's code.
+
 ---

 ## Logging
This commit is contained in:
Inutt committed 2025-11-24 20:14:51 +00:00
1 parent b9f3cf3d6a
commit f4e70dbe5b
1 file changed
+13
+13
View File
@@ -163,6 +163,19 @@ circular imports.
For an example of how this is done, look at the code in `plugins/common_coreutils.py`
and the usage of these functions in other core plugins.
Plugins may import additional code modules from `load.py` in the usual way. Note
that using an import statement like `import my_module` or `from my_module import
foo` will only import one module with that name **across all plugins**. This can
be used to create a shared library used by several plugins if used carefully,
but may create a conflict if another plugin also has a module of the same name
containing different code. For example if two plugins both contain a
`widgets.py` file and both do `import widgets`, only one of the two modules will
actually be imported.
To avoid this issue, use a relative import statement such as `import .widgets`
or `from .widgets import foo` to ensure that the module is loaded from the
current plugin, even if the name conflicts with another plugin's code.
---
## Logging