Skip to content

Commit 2430bfb

Browse files
committed
feat: load a plugin entrypoint as a package
The loader accepted a single <module>.py next to the manifest and never registered it in sys.modules, so a plugin could not split its tables across files. A <module>/__init__.py is now loaded as a package with its directory as search location and registered under its path-derived name before it runs, which is what its relative imports resolve through. Closes #93
1 parent 09c5444 commit 2430bfb

3 files changed

Lines changed: 30 additions & 3 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Changelog
22

3+
## Unreleased
4+
5+
### Plugins
6+
7+
- A plugin's entrypoint may be a package, `<module>/__init__.py`, so a plugin can split its tables across files and import them relatively (#93).
8+
39
## 0.2.0 (2026-09-06)
410

511
### Adoption in an existing repository

‎docs/plugins.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,12 @@ class = "SensitiveLoggingPlugin"
3838
| `plugin_api` | The range of plugin API versions the plugin supports. The current API is version 1. |
3939
| `requires` | Capabilities the plugin needs; a mismatch with the class's `requires` is a manifest error. |
4040
| `provides` | Capabilities the plugin offers, for documentation and conflict detection. |
41-
| `entrypoint` | The module file (without `.py`, next to the manifest) and the class in it. |
41+
| `entrypoint` | The module (without `.py`, next to the manifest) and the class in it. |
42+
43+
The entrypoint module may be a package, `<module>/__init__.py`, when a plugin grows past
44+
one file: its submodules are reached through relative imports (`from .tables import
45+
celery`). Two plugins may use the same module name; each is imported under a name derived
46+
from its path.
4247

4348
## Symbols
4449

‎src/coretrace_python/plugins/loader.py‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
import hashlib
66
import importlib.util
7+
import sys
78
from dataclasses import dataclass
89
from pathlib import Path
910

@@ -63,16 +64,31 @@ def discover_plugins(root: Path, manager: AnalysisManager) -> tuple[LoadedPlugin
6364

6465

6566
def _import_entrypoint(directory: Path, manifest: PluginManifest) -> type[Plugin]:
66-
module_path = directory / f"{manifest.entrypoint.module}.py"
67+
"""Import the entrypoint, a module ``<name>.py`` or a package ``<name>/__init__.py``.
68+
69+
The module name derives from the path, so two plugins may both call their module
70+
``models``; a package is registered in ``sys.modules`` under that name before it
71+
runs, which is what its relative imports resolve through."""
72+
73+
package_path = directory / manifest.entrypoint.module / "__init__.py"
74+
is_package = package_path.is_file()
75+
module_path = package_path if is_package else directory / f"{manifest.entrypoint.module}.py"
6776
if not module_path.is_file():
6877
raise ManifestError(
6978
f"{directory / MANIFEST_FILENAME}: entrypoint module"
7079
f" {manifest.entrypoint.module!r} not found"
7180
)
7281
unique = hashlib.sha1(str(module_path.resolve()).encode()).hexdigest()[:12]
73-
spec = importlib.util.spec_from_file_location(f"coretrace_plugin_{unique}", module_path)
82+
name = f"coretrace_plugin_{unique}"
83+
spec = importlib.util.spec_from_file_location(
84+
name,
85+
module_path,
86+
submodule_search_locations=[str(module_path.parent)] if is_package else None,
87+
)
7488
assert spec is not None and spec.loader is not None
7589
module = importlib.util.module_from_spec(spec)
90+
if is_package:
91+
sys.modules[name] = module
7692
spec.loader.exec_module(module)
7793

7894
candidate = getattr(module, manifest.entrypoint.class_name, None)

0 commit comments

Comments
 (0)