Add the mvt.plugin import surface

mvt.plugin re-exports the names a plugin needs from MVT under one import
path. It holds the module base classes and Command, the alert and result
types, the database errors a module raises, the timestamp converters, the
plugin settings API, MVT's settings, get_plugin_logger() and MVT_VERSION.

The names it exports are kept working on a best-effort basis. Changes to
them are announced in the release notes. Anything else in mvt can still be
imported, and may change between releases without notice.

get_plugin_logger(__name__) returns a logger under mvt.ext for plugin code
outside a module class. Its records then reach the console and the
command.log file of a run. A file loaded with --load-module or
--load-command is named after the file.

src/mvt/common/cli_plugins.py

@@ -15,6 +15,8 @@ from typing import Iterable
 
 import click
 
+from .module_loader import CUSTOM_COMMAND_MODULE_PREFIX
+
 IOS_CLI_PLUGIN_GROUP = "mvt.ios.cli_plugins"
 ANDROID_CLI_PLUGIN_GROUP = "mvt.android.cli_plugins"
 # Commands in this group are registered on the platform-neutral mvt command only.
@@ -57,7 +59,7 @@ class BrokenPluginCommand(click.Command):
 
 def _module_name_for_path(path: Path) -> str:
     digest = hashlib.sha256(str(path).encode("utf-8")).hexdigest()[:16]
-    return f"_mvt_custom_command_{path.stem}_{digest}"
+    return f"{CUSTOM_COMMAND_MODULE_PREFIX}{path.stem}_{digest}"
 
 
 def _iter_command_files(path: Path) -> Iterable[Path]:

src/mvt/common/module_loader.py

@@ -10,6 +10,7 @@ import inspect
 import json
 import logging
 import os
+import re
 import sys
 from dataclasses import dataclass
 from functools import lru_cache
@@ -26,6 +27,9 @@ EXTERNAL_LOGGER_NAMESPACE = "mvt.ext"
 PLUGIN_PACKAGE_PREFIX = "mvt_plugin_"
 _ORIGIN_ATTRIBUTE = "_mvt_module_origin"
 _PATH_MODULE_PREFIX = "_mvt_custom_module_"
+# Shared with cli_plugins, which names a loaded command file this way.
+CUSTOM_COMMAND_MODULE_PREFIX = "_mvt_custom_command_"
+_LOADED_FILE_DIGEST = re.compile(r"_[0-9a-f]{16}$")
 log = logging.getLogger(__name__)
 
 
@@ -66,6 +70,25 @@ def _module_name_for_path(path: Path) -> str:
     return f"{_PATH_MODULE_PREFIX}{path.stem}_{digest}"
 
 
+def _is_builtin_logger_name(name: str) -> bool:
+    return name == "mvt" or name.startswith("mvt.")
+
+
+def _loaded_file_stem(name: str, prefix: str) -> str:
+    """Recover a loaded file's name from the import name MVT gave it."""
+    return _LOADED_FILE_DIGEST.sub("", name[len(prefix) :])
+
+
+def _external_logger_name(name: str) -> str:
+    """Return the "mvt.ext" logger name external code logs under."""
+    top_level, separator, rest = name.partition(".")
+    if top_level.startswith(PLUGIN_PACKAGE_PREFIX) and len(top_level) > len(
+        PLUGIN_PACKAGE_PREFIX
+    ):
+        name = top_level[len(PLUGIN_PACKAGE_PREFIX) :] + separator + rest
+    return f"{EXTERNAL_LOGGER_NAMESPACE}.{name}"
+
+
 def get_module_logger(module_class: type[MVTModule]) -> logging.Logger:
     """Return the logger a module's records should be emitted through.
 
@@ -80,19 +103,35 @@ def get_module_logger(module_class: type[MVTModule]) -> logging.Logger:
     "mvt_plugin_<name>" naming convention log under "mvt.ext.<name>".
     """
     name = module_class.__module__
-    if name == "mvt" or name.startswith("mvt."):
+    if _is_builtin_logger_name(name):
         return logging.getLogger(name)
 
     if name.startswith(_PATH_MODULE_PREFIX):
-        name = Path(get_module_origin(module_class).name).stem
-    else:
-        top_level, separator, rest = name.partition(".")
-        if top_level.startswith(PLUGIN_PACKAGE_PREFIX) and len(top_level) > len(
-            PLUGIN_PACKAGE_PREFIX
-        ):
-            name = top_level[len(PLUGIN_PACKAGE_PREFIX) :] + separator + rest
+        file_name = Path(get_module_origin(module_class).name).stem
+        return logging.getLogger(f"{EXTERNAL_LOGGER_NAMESPACE}.{file_name}")
 
-    return logging.getLogger(f"{EXTERNAL_LOGGER_NAMESPACE}.{name}")
+    return logging.getLogger(_external_logger_name(name))
+
+
+def get_plugin_logger(name: str) -> logging.Logger:
+    """Return a general logger for use in custom MVT plugins.
+
+    Call it with ``__name__``. The logger sits under "mvt.ext". That is
+    where get_module_logger() puts module classes. A file loaded with
+    --load-module or --load-command is named after the file.
+    """
+    if _is_builtin_logger_name(name):
+        return logging.getLogger(name)
+
+    # A file loaded with --load-module or --load-command is imported under a
+    # mangled name. Log it under the file it came from. get_module_logger()
+    # does the same for the module classes such a file defines.
+    for prefix in (_PATH_MODULE_PREFIX, CUSTOM_COMMAND_MODULE_PREFIX):
+        if name.startswith(prefix):
+            stem = _loaded_file_stem(name, prefix)
+            return logging.getLogger(f"{EXTERNAL_LOGGER_NAMESPACE}.{stem}")
+
+    return logging.getLogger(_external_logger_name(name))
 
 
 def _iter_module_files(path: Path) -> Iterable[Path]:

src/mvt/plugin.py

@@ -0,0 +1,80 @@
+# Mobile Verification Toolkit (MVT)
+# Copyright (c) 2021-2026 The MVT Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
+
+"""Stable functions and modules which plugins can import.
+
+Anything else in mvt can be imported too, and may change
+between releases without notice.
+"""
+
+from mvt.android.modules.androidqf.base import AndroidQFModule
+from mvt.android.modules.backup.base import BackupModule as AndroidBackupModule
+from mvt.android.modules.bugreport.base import BugReportModule
+from mvt.common.alerts import Alert, AlertLevel
+from mvt.common.command import Command
+from mvt.common.config import settings
+from mvt.common.module import DatabaseCorruptedError, DatabaseNotFoundError, MVTModule
+from mvt.common.module_loader import get_plugin_logger
+from mvt.common.module_types import (
+    ModuleAtomicResult,
+    ModuleResults,
+    ModuleSerializedResult,
+)
+from mvt.common.plugin_config import (
+    MVTPluginSettings,
+    PluginConfigLoadError,
+    plugin_config_path,
+    plugin_data_folder,
+    plugin_env_prefix,
+)
+from mvt.common.utils import (
+    convert_chrometime_to_datetime,
+    convert_datetime_to_iso,
+    convert_mactime_to_datetime,
+    convert_mactime_to_iso,
+    convert_unix_to_iso,
+    convert_unix_to_utc_datetime,
+)
+from mvt.common.version import MVT_VERSION
+from mvt.ios.modules.base import IOSExtraction
+from mvt.ios.modules.sysdiagnose.base import SysdiagnoseExtraction
+
+__all__ = [
+    # Classes a plugin subclasses.
+    "MVTModule",
+    "IOSExtraction",
+    "SysdiagnoseExtraction",
+    "AndroidQFModule",
+    "AndroidBackupModule",
+    "BugReportModule",
+    "Command",
+    # Results and alerts.
+    "ModuleAtomicResult",
+    "ModuleResults",
+    "ModuleSerializedResult",
+    "Alert",
+    "AlertLevel",
+    # Errors a module raises.
+    "DatabaseNotFoundError",
+    "DatabaseCorruptedError",
+    # Settings.
+    "settings",
+    "MVTPluginSettings",
+    "PluginConfigLoadError",
+    "plugin_config_path",
+    "plugin_data_folder",
+    "plugin_env_prefix",
+    # Logging.
+    "get_plugin_logger",
+    # Timestamps.
+    "convert_chrometime_to_datetime",
+    "convert_datetime_to_iso",
+    "convert_mactime_to_datetime",
+    "convert_mactime_to_iso",
+    "convert_unix_to_iso",
+    "convert_unix_to_utc_datetime",
+    # MVT's version.
+    "MVT_VERSION",
+]

tests/common/test_module_loader.py

@@ -1,9 +1,14 @@
+from pathlib import Path
+
 import pytest
 
+from mvt.common.cli_plugins import _module_name_for_path as _command_module_name
 from mvt.common.module import MVTModule
 from mvt.common.module_loader import (
     CustomModuleLoadError,
+    _module_name_for_path,
     get_module_logger,
+    get_plugin_logger,
     load_custom_modules,
     load_custom_modules_from_path,
     module_supports_command,
@@ -168,9 +173,9 @@ def test_get_module_logger_strips_the_plugin_package_prefix():
     class PluginModule(MVTModule):
         pass
 
-    PluginModule.__module__ = "mvt_plugin_amnesty_custom.ios.custom"
+    PluginModule.__module__ = "mvt_plugin_example_org.ios.custom"
 
-    assert get_module_logger(PluginModule).name == "mvt.ext.amnesty_custom.ios.custom"
+    assert get_module_logger(PluginModule).name == "mvt.ext.example_org.ios.custom"
 
 
 def test_get_module_logger_only_strips_the_prefix_from_the_top_level():
@@ -187,3 +192,25 @@ def test_get_module_logger_names_path_modules_after_their_file(tmp_path):
     module = load_custom_modules_from_path(str(module_path))[0]
 
     assert get_module_logger(module).name == "mvt.ext.my_custom_module"
+
+
+def test_get_plugin_logger_uses_the_same_namespace_as_modules():
+    assert (
+        get_plugin_logger("mvt_plugin_example_org.commands.summarize").name
+        == "mvt.ext.example_org.commands.summarize"
+    )
+    assert get_plugin_logger("example_plugin.cli").name == "mvt.ext.example_plugin.cli"
+
+
+def test_get_plugin_logger_keeps_builtin_names():
+    assert get_plugin_logger("mvt.ios.cli").name == "mvt.ios.cli"
+
+
+def test_get_plugin_logger_names_loaded_files_after_the_file():
+    # A file loaded with --load-command or --load-module is imported under a
+    # mangled name. The log names the file instead.
+    command_name = _command_module_name(Path("/tmp/case_summary.py"))
+    module_name = _module_name_for_path(Path("/tmp/my_custom_module.py"))
+
+    assert get_plugin_logger(command_name).name == "mvt.ext.case_summary"
+    assert get_plugin_logger(module_name).name == "mvt.ext.my_custom_module"

tests/common/test_plugin.py

@@ -0,0 +1,34 @@
+# Mobile Verification Toolkit (MVT)
+# Copyright (c) 2021-2026 The MVT Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
+
+import mvt.plugin
+from mvt.android.modules.backup.base import BackupModule
+from mvt.common.config import settings
+
+from ..plugin_fixtures import run_isolated_python
+
+
+def test_the_exported_names_are_the_public_names():
+    public = {name for name in vars(mvt.plugin) if not name.startswith("_")}
+
+    assert public == set(mvt.plugin.__all__)
+    assert mvt.plugin.settings is settings
+    assert mvt.plugin.AndroidBackupModule is BackupModule
+
+
+def test_the_surface_imports_before_anything_else_of_mvt(tmp_path):
+    # A plugin can import the surface as its first import of MVT. The
+    # subprocess gets a temporary home because importing MVT writes its
+    # configuration file.
+    result = run_isolated_python(
+        "from mvt.plugin import IOSExtraction, MVT_VERSION, settings\n"
+        "assert MVT_VERSION\n"
+        "assert settings.NETWORK_TIMEOUT > 0\n"
+        "assert IOSExtraction.__name__ == 'IOSExtraction'\n",
+        home=tmp_path,
+    )
+
+    assert result.returncode == 0, result.stderr
+    assert result.stderr == ""

tests/plugin_fixtures.py

@@ -73,6 +73,7 @@ def run_isolated_python(
     }
     isolated_environment["HOME"] = str(home)
     isolated_environment["XDG_CONFIG_HOME"] = str(home / "config")
+    isolated_environment["XDG_DATA_HOME"] = str(home / "data")
     if site_path is not None:
         isolated_environment["PYTHONPATH"] = str(site_path)
     isolated_environment.update(environment)