aphelion-plugin-sdk 0.1.0__py3-none-any.whl

aphelion_plugin_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: aphelion-plugin-sdk
+Version: 0.1.0
+Summary: Public SDK for Aphelion plugins (video now; audio later).
+Author: youthx
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://github.com/aphelion-engine/aphelion-sdk
+Project-URL: Repository, https://github.com/aphelion-engine/aphelion-sdk
+Keywords: aphelion,plugin,sdk,video,audio
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.26.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+
+# Aphelion Plugin SDK
+
+Public API for plugins that run **inside Aphelion Editor**. This package sits beside `aphelion-editor`, not inside it.
+
+Import **`aphelion_sdk` only**. Never import `core`, `effects`, `render`, or `ui`.
+
+Video effects are available now (`VideoEffectPlugin`). Audio bases will land under `aphelion_sdk.audio` later.
+
+Version **0.1.0**. Python **3.11+**. Install with **`pip install aphelion-plugin-sdk`**. Import **`aphelion_sdk`**.
+
+## Install
+
+```bash
+pip install aphelion-plugin-sdk
+```
+
+From the `aphelion-engine` root, with a venv active:
+
+```bash
+pip install -e ./aphelion-editor
+pip install -e ./aphelion-sdk
+```
+
+Installing the editor already depends on this package (`aphelion-plugin-sdk @ file:../aphelion-sdk`).
+
+```bash
+aphelion-sdk --version
+python -m aphelion_sdk --help
+```
+
+## Quick start
+
+```python
+import aphelion_sdk
+
+
+@aphelion_sdk.register_plugin
+class GrayscaleEffect(aphelion_sdk.VideoEffectPlugin):
+    plugin_name = "Grayscale"
+    plugin_category = "Plugins"
+    plugin_description = "Blend a frame toward grayscale."
+    plugin_color = (140, 140, 140)
+
+    def setup_effect_properties(self) -> None:
+        self.set_property(
+            "amount",
+            aphelion_sdk.slider_property(
+                100, 0, 100,
+                label="Amount",
+                suffix="%",
+            ),
+        )
+
+    def process_frame(
+        self,
+        frame: aphelion_sdk.Frame,
+        _frame_num: int,
+    ) -> aphelion_sdk.Frame:
+        amount = self.float_value("amount", 100.0) / 100.0
+        luma = (
+            frame[..., 0] * 0.2126
+            + frame[..., 1] * 0.7152
+            + frame[..., 2] * 0.0722
+        )
+        gray = luma[..., None].repeat(3, axis=2)
+        return frame * (1.0 - amount) + gray * amount
+```
+
+Drop the file in the editor's `plugins/` or `userdata/plugins/`, or pack a wheel (below). Time-independent effects should name the unused argument `_frame_num`.
+
+Examples:
+
+- [`examples/grayscale_effect.py`](examples/grayscale_effect.py)
+- [`examples/effect_with_widget.py`](examples/effect_with_widget.py) — dialog + panel via `widgets = (...)`
+
+## Documentation
+
+| Guide | Contents |
+|---|---|
+| [Authoring](docs/authoring.md) | Effect class, properties, discovery rules |
+| [Widgets](docs/widgets.md) | Panels, dialogs, primitives, PyQt6 |
+| [API reference](docs/api.md) | Public symbols |
+| [Packaging](docs/packaging.md) | `aphelion-sdk build`, entry points, drop-in install |
+| [Editor plugins](../aphelion-editor/docs/plugins.md) | How the host loads and reloads plugins |
+
+## Package a plugin
+
+```bash
+aphelion-sdk build examples/grayscale_effect.py -o dist
+pip install dist/aphelion_plugin_grayscale-*.whl
+```
+
+Entry point group: `aphelion.plugins`. Widgets are declared on the plugin (`widgets = (MyDialog, MyPanel)`); they are not registered on their own.
+
+## License
+
+Proprietary (`LicenseRef-Proprietary` in `pyproject.toml`).

aphelion_plugin_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,39 @@
+aphelion_sdk/__init__.py,sha256=Tq_JL8Zd0VdUWfVByLowWvHbkciAqP_wwOoUMkR1-us,5180
+aphelion_sdk/__main__.py,sha256=W5PU-J3zrWyMLkpkWOo9q8RG0ah2Da2Ua-kMsUZkVKY,215
+aphelion_sdk/plugin.py,sha256=IiVSVH7V_20dr9knFdF_jsKwytGduKNBnUa-iB3FAGk,2053
+aphelion_sdk/properties.py,sha256=Wq_ChTMZaKltNup3OpLtFIeuFEehTyVntGEY3ma1GSQ,4764
+aphelion_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aphelion_sdk/registration.py,sha256=ZnKewc1Vd2eZEwSJeG-MIYJiPt3NgDObxPaEZ9wmVQE,2805
+aphelion_sdk/types.py,sha256=fcQrZyIKw51Mh8nNWbKeDZKlGaz7NgO8kqhaRff0j78,602
+aphelion_sdk/version.py,sha256=DRDKPdzt6Ku28r5lgFuYvtmulhod8TmfX2b8UVmtql8,169
+aphelion_sdk/audio/__init__.py,sha256=lQAb4POqnfot3fbg_UZiezJD1cH9CBBZXwFBAJziJxg,185
+aphelion_sdk/cli/__init__.py,sha256=qAkOQZWWPoll4T5pGsVNsfWAsqwMF0hVXn2WQ3bM6mU,161
+aphelion_sdk/cli/main.py,sha256=oxxmG-phVV9tk6TwMoWUIYHSJsB3tqnVNSVnXnjpr9g,6609
+aphelion_sdk/host/__init__.py,sha256=7SYdewYdfYLAYxXqu97JE_KQlAXmWSnyPKbPVT99rPI,511
+aphelion_sdk/host/constants.py,sha256=_M3EsBRX5IlhjrwQKwFAvtROrvIjP-XNv8iAJVfM2e8,704
+aphelion_sdk/host/errors.py,sha256=uRRcUQjWjuwfS-F0sZ-QKj8WD39V7POt0MhdrhNJRQc,419
+aphelion_sdk/host/install.py,sha256=yl-2DKiMx5-4rKCXET5qyZA1cL2RCKpWMwuJuAlG2xY,1973
+aphelion_sdk/host/locate.py,sha256=lTFxnBD6_BKfn8LimDXx8IpqyNJtvnPKfx8IDTBcQRQ,2809
+aphelion_sdk/host/models.py,sha256=XiCHewoaCDpNmOpyuwvkjIW1butlR4AyVODSEem4jmk,1063
+aphelion_sdk/host/validate.py,sha256=gzHHbuUC7LJx0ywO55seWVOghZWrvUpcyaA2RZca0qc,2315
+aphelion_sdk/host/windows.py,sha256=bCJf0-_5pNwDBegNJtvGaeFPgrXrhXP_961QL_Y_DHg,2607
+aphelion_sdk/packaging/__init__.py,sha256=4WH_jAHxnxngsopPXcX3o2Y5bsXSa8oRGWO9XPhwfNg,666
+aphelion_sdk/packaging/builder.py,sha256=qTtDsS9mXMaLyJDZr94jcl0oBvvQXh07_lOnEW_6O2c,7548
+aphelion_sdk/packaging/discovery.py,sha256=mLV19IH2xVIQZcPAeL6YCfqLu6T2RU8s61GQF4x5Y_U,8979
+aphelion_sdk/packaging/errors.py,sha256=ihIpSNHrBu_opkI8Mf-KGCbyiQh-T5TnPH_irV5TqqA,408
+aphelion_sdk/packaging/names.py,sha256=MD7uWXWQSj8QZBU8GkbEPE-f4WAuAnvMLDUxoOIfd2k,4958
+aphelion_sdk/packaging/project.py,sha256=Y0eTQfJhZyWmaXU4kSG-coXfUuyi3SJsgwagsrMN8I8,7822
+aphelion_sdk/video/__init__.py,sha256=XHct9Eu4DixPmYkm6q3Gn4tLiuw1flnQ6rUvebnFeKc,211
+aphelion_sdk/video/effect.py,sha256=b_YkK7zetpoi78RxcVVve9c7N6w2xV5X5_i5UIb88O0,3125
+aphelion_sdk/widgets/__init__.py,sha256=9RDyHzzIgMm9RgNTyVqasuVHa2IblJDP2WiuT4z683c,737
+aphelion_sdk/widgets/base.py,sha256=TtOpx6zfSNeafMH6Hsn9v_R3AvNHA_BD2pY8ztVcUAs,2841
+aphelion_sdk/widgets/dialog.py,sha256=8s1_sw82UobBotm7EWTAjts2NYjPmNNuRxOFvTIWrUI,1669
+aphelion_sdk/widgets/host.py,sha256=xjH6Ksuq97nl-I89IAielZZOQDIH-LdyO7KDOB2rApw,3512
+aphelion_sdk/widgets/kinds.py,sha256=QU1u83-ReEShDk9Je7Di6yPJ4JWJPRu2nbzYueaBKzY,438
+aphelion_sdk/widgets/panel.py,sha256=wPk8tUtfzgsRSY1HNMuP26N2tggX9wZKwSR2GhBGk6I,1237
+aphelion_sdk/widgets/qt.py,sha256=hnXj3OchPzF4lMw15tnT9E0NJK_-0CDI4nPuzte1jIs,950
+aphelion_plugin_sdk-0.1.0.dist-info/METADATA,sha256=IZgE7lNQ0bbGvJUg-i5rDDPcF4HeEfO_JCr5erelnkA,3660
+aphelion_plugin_sdk-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+aphelion_plugin_sdk-0.1.0.dist-info/entry_points.txt,sha256=st-HkX1WMH1MzN4mqFMZ4lQaAXgMhI-Nw-kh52d_sfI,60
+aphelion_plugin_sdk-0.1.0.dist-info/top_level.txt,sha256=tx-w30xPZbHoZHSQdaIC6GatkPMGdnC1mh6hEixMgRw,13
+aphelion_plugin_sdk-0.1.0.dist-info/RECORD,,

aphelion_plugin_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aphelion_plugin_sdk-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+aphelion-sdk = aphelion_sdk.cli.main:main

aphelion_plugin_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+aphelion_sdk

aphelion_sdk/__init__.py

@@ -0,0 +1,151 @@
+"""Aphelion Plugin SDK.
+
+Public, stable surface for custom Aphelion plugins. Authors should
+``import aphelion_sdk`` and must never import editor internals
+(``core``, ``effects``, ``render``, ``ui``).
+
+Video effects subclass ``VideoEffectPlugin``. Attach UI with
+``widgets = (MyDialog, MyPanel)``. Simple widgets use host primitives;
+advanced widgets may import PyQt6 and return a ``QWidget`` from
+``build_qt_widget`` or ``embed_native``.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from aphelion_sdk.plugin import Plugin
+    from aphelion_sdk.properties import (
+        PluginProperty,
+        choice_property,
+        color_property,
+        custom_property,
+        number_property,
+        slider_property,
+        text_property,
+        toggle_property,
+    )
+    from aphelion_sdk.registration import (
+        clear_registered_plugins,
+        discover_installed_plugins,
+        get_registered_plugins,
+        register_plugin,
+    )
+    from aphelion_sdk.types import ColorRgb, Frame
+    from aphelion_sdk.version import __version__
+    from aphelion_sdk.video import VideoEffectPlugin
+    from aphelion_sdk.widgets import (
+        DialogWidget,
+        PanelWidget,
+        PluginWidget,
+        WidgetContext,
+        WidgetHost,
+        WidgetView,
+        coerce_qt_parent,
+        is_qt_widget,
+    )
+
+__all__ = [
+    "ColorRgb",
+    "DialogWidget",
+    "Frame",
+    "PanelWidget",
+    "Plugin",
+    "PluginProperty",
+    "PluginWidget",
+    "VideoEffectPlugin",
+    "WidgetContext",
+    "WidgetHost",
+    "WidgetView",
+    "__version__",
+    "choice_property",
+    "clear_registered_plugins",
+    "coerce_qt_parent",
+    "color_property",
+    "custom_property",
+    "discover_editors",
+    "discover_installed_plugins",
+    "get_registered_plugins",
+    "install_plugins_into_editor",
+    "locate_editor",
+    "is_qt_widget",
+    "number_property",
+    "register_plugin",
+    "slider_property",
+    "text_property",
+    "toggle_property",
+]
+
+_EXPORT_MAP: Final[dict[str, tuple[str, str]]] = {
+    "ColorRgb": ("aphelion_sdk.types", "ColorRgb"),
+    "DialogWidget": ("aphelion_sdk.widgets.dialog", "DialogWidget"),
+    "Frame": ("aphelion_sdk.types", "Frame"),
+    "PanelWidget": ("aphelion_sdk.widgets.panel", "PanelWidget"),
+    "Plugin": ("aphelion_sdk.plugin", "Plugin"),
+    "PluginProperty": ("aphelion_sdk.properties", "PluginProperty"),
+    "PluginWidget": ("aphelion_sdk.widgets.base", "PluginWidget"),
+    "VideoEffectPlugin": ("aphelion_sdk.video", "VideoEffectPlugin"),
+    "WidgetContext": ("aphelion_sdk.widgets.host", "WidgetContext"),
+    "WidgetHost": ("aphelion_sdk.widgets.host", "WidgetHost"),
+    "WidgetView": ("aphelion_sdk.widgets.host", "WidgetView"),
+    "__version__": ("aphelion_sdk.version", "__version__"),
+    "choice_property": ("aphelion_sdk.properties", "choice_property"),
+    "clear_registered_plugins": (
+        "aphelion_sdk.registration",
+        "clear_registered_plugins",
+    ),
+    "coerce_qt_parent": ("aphelion_sdk.widgets.qt", "coerce_qt_parent"),
+    "color_property": ("aphelion_sdk.properties", "color_property"),
+    "custom_property": ("aphelion_sdk.properties", "custom_property"),
+    "discover_editors": ("aphelion_sdk.host.locate", "discover_editors"),
+    "discover_installed_plugins": (
+        "aphelion_sdk.registration",
+        "discover_installed_plugins",
+    ),
+    "install_plugins_into_editor": (
+        "aphelion_sdk.host.install",
+        "install_plugins_into_editor",
+    ),
+    "locate_editor": ("aphelion_sdk.host.locate", "locate_editor"),
+    "get_registered_plugins": (
+        "aphelion_sdk.registration",
+        "get_registered_plugins",
+    ),
+    "is_qt_widget": ("aphelion_sdk.widgets.qt", "is_qt_widget"),
+    "number_property": ("aphelion_sdk.properties", "number_property"),
+    "register_plugin": ("aphelion_sdk.registration", "register_plugin"),
+    "slider_property": ("aphelion_sdk.properties", "slider_property"),
+    "text_property": ("aphelion_sdk.properties", "text_property"),
+    "toggle_property": ("aphelion_sdk.properties", "toggle_property"),
+}
+
+
+def __getattr__(name: str) -> object:
+    """Resolve a public SDK symbol on first access.
+
+    Parameters:
+        name: Attribute requested on ``aphelion_sdk``.
+
+    Returns:
+        The exported object bound to ``name``.
+
+    Exceptions:
+        AttributeError: If ``name`` is not part of the public surface.
+
+    Side effects:
+        Imports the implementing submodule and caches the attribute.
+    """
+    location: tuple[str, str] | None = _EXPORT_MAP.get(name)
+    if location is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module_name, attr_name = location
+    value: object = getattr(import_module(module_name), attr_name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Return module attributes including lazy public exports."""
+    return sorted(set(globals()) | set(_EXPORT_MAP))

aphelion_sdk/__main__.py

@@ -0,0 +1,10 @@
+"""Allow ``python -m aphelion_sdk`` to invoke the packaging CLI."""
+
+from __future__ import annotations
+
+import sys
+
+from aphelion_sdk.cli.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

aphelion_sdk/audio/__init__.py

@@ -0,0 +1,9 @@
+"""Audio plugin bases.
+
+Not implemented in this release. Video effects use
+``aphelion_sdk.VideoEffectPlugin``.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

aphelion_sdk/cli/__init__.py

@@ -0,0 +1,7 @@
+"""Command-line interface for the Aphelion Plugin SDK."""
+
+from __future__ import annotations
+
+from aphelion_sdk.cli.main import main
+
+__all__ = ["main"]

aphelion_sdk/cli/main.py

@@ -0,0 +1,203 @@
+"""Argparse entry for ``aphelion-sdk`` and ``python -m aphelion_sdk``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from aphelion_sdk.host import EditorHostError, EditorInstall, locate_editor
+from aphelion_sdk.host.install import install_plugins_into_editor
+from aphelion_sdk.packaging import (
+    PackageBuildResult,
+    PluginPackageError,
+    build_plugin_package,
+)
+from aphelion_sdk.version import DISTRIBUTION_NAME, __version__
+
+_DESCRIPTION: str = (
+    "Build Aphelion plugins, locate the installed editor, and copy "
+    "drop-in plugins into that editor. Pass a .py file or plugin "
+    "directory to wrap it, or a project root with pyproject.toml "
+    "to run a standard PEP 517 build."
+)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Parse CLI arguments and dispatch the requested command.
+
+    Parameters:
+        argv: Argument vector without the program name. Defaults to
+            ``sys.argv[1:]``.
+
+    Returns:
+        Process exit code. ``0`` on success, ``1`` on packaging errors,
+        ``2`` on usage errors (argparse).
+
+    Exceptions:
+        None. Packaging failures are printed to stderr.
+
+    Side effects:
+        May write wheel files and print status to stdout/stderr.
+    """
+    parser: argparse.ArgumentParser = _build_parser()
+    args: argparse.Namespace = parser.parse_args(list(argv) if argv is not None else None)
+    command: str | None = args.command
+    if command == "build":
+        return _handle_build(args)
+    if command == "locate":
+        return _handle_locate()
+    if command == "install":
+        return _handle_install(args)
+    parser.print_help()
+    return 2
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Return the root parser with the ``build`` subcommand."""
+    parser = argparse.ArgumentParser(prog="aphelion-sdk", description=_DESCRIPTION)
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"{DISTRIBUTION_NAME} {__version__}",
+    )
+    subparsers = parser.add_subparsers(dest="command", metavar="COMMAND")
+    _add_build_parser(subparsers)
+    _add_locate_parser(subparsers)
+    _add_install_parser(subparsers)
+    return parser
+
+
+def _add_build_parser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    """Register ``aphelion-sdk build``."""
+    parser = subparsers.add_parser(
+        "build",
+        help="Build a pip wheel from plugin source or an existing project.",
+    )
+    parser.add_argument(
+        "source",
+        nargs="?",
+        type=Path,
+        default=Path.cwd(),
+        help="Plugin .py file, plugin directory, or project root (default: cwd).",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=Path.cwd() / "dist",
+        help="Directory for built artifacts (default: ./dist).",
+    )
+    _add_build_metadata_flags(parser)
+
+
+def _add_locate_parser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    """Register ``aphelion-sdk locate``."""
+    subparsers.add_parser(
+        "locate",
+        help="Print the Aphelion Editor install this SDK will target.",
+    )
+
+
+def _add_install_parser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    """Register ``aphelion-sdk install``."""
+    parser = subparsers.add_parser(
+        "install",
+        help="Copy plugin sources into the located editor's userdata/plugins.",
+    )
+    parser.add_argument(
+        "source",
+        type=Path,
+        help="Plugin .py file or directory of plugin modules.",
+    )
+
+
+def _handle_locate() -> int:
+    """Print the discovered editor install."""
+    try:
+        install: EditorInstall = locate_editor()
+    except EditorHostError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    kind: str = "frozen" if install.is_frozen else "source"
+    print(f"root: {install.root}")
+    print(f"executable: {install.executable}")
+    print(f"plugins: {install.user_plugin_dir}")
+    print(f"version: {install.version or '(unknown)'}")
+    print(f"source: {install.source} ({kind})")
+    return 0
+
+
+def _handle_install(args: argparse.Namespace) -> int:
+    """Copy plugin files into the located editor."""
+    try:
+        written: tuple[Path, ...] = install_plugins_into_editor(args.source)
+    except (EditorHostError, PluginPackageError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print(f"Installed {len(written)} plugin file(s) into {written[0].parent}")
+    for path in written:
+        print(f"  {path}")
+    return 0
+
+
+def _add_build_metadata_flags(parser: argparse.ArgumentParser) -> None:
+    """Attach optional package-identity flags to the build parser."""
+    parser.add_argument(
+        "-n",
+        "--name",
+        default=None,
+        help="Distribution name (generated packages only).",
+    )
+    parser.add_argument(
+        "--package-version",
+        default="0.1.0",
+        help="Package version for generated packages (default: 0.1.0).",
+    )
+    parser.add_argument(
+        "--author",
+        default=None,
+        help="Package author (generated packages only).",
+    )
+    parser.add_argument(
+        "--description",
+        default=None,
+        help="Package summary (generated packages only).",
+    )
+
+
+def _handle_build(args: argparse.Namespace) -> int:
+    """Run the packaging builder and print the resulting artifacts."""
+    source: Path = args.source
+    output: Path = args.output
+    try:
+        result: PackageBuildResult = build_plugin_package(
+            source,
+            output,
+            distribution_name=args.name,
+            version=args.package_version,
+            author=args.author,
+            description=args.description,
+        )
+    except PluginPackageError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    _print_success(result)
+    return 0
+
+
+def _print_success(result: PackageBuildResult) -> None:
+    """Write a short build summary to stdout."""
+    kind: str = "project" if result.mode == "project" else "plugin package"
+    print(f"Built {kind} {result.distribution_name} {result.version}")
+    for plugin in result.plugins:
+        print(f"  plugin: {plugin.plugin_name} ({plugin.class_name})")
+    for artifact in result.artifacts:
+        print(f"  {artifact}")

aphelion_sdk/host/__init__.py

@@ -0,0 +1,16 @@
+"""Locate the installed Aphelion Editor and install drop-in plugins into it."""
+
+from __future__ import annotations
+
+from aphelion_sdk.host.errors import EditorHostError
+from aphelion_sdk.host.install import install_plugins_into_editor
+from aphelion_sdk.host.locate import discover_editors, locate_editor
+from aphelion_sdk.host.models import EditorInstall
+
+__all__ = [
+    "EditorHostError",
+    "EditorInstall",
+    "discover_editors",
+    "install_plugins_into_editor",
+    "locate_editor",
+]

aphelion_sdk/host/constants.py

@@ -0,0 +1,17 @@
+"""Shared names used to locate an Aphelion Editor install."""
+
+from __future__ import annotations
+
+from typing import Final
+
+ENV_EDITOR_HOME: Final[str] = "APHELION_EDITOR_HOME"
+HOST_MANIFEST_NAME: Final[str] = "aphelion-host.json"
+EDITOR_EXE_NAME: Final[str] = "AphelionEditor.exe"
+SOURCE_ENTRY_NAME: Final[str] = "main.py"
+REGISTRY_KEY: Final[str] = r"Software\Aphelion\Editor"
+REGISTRY_VALUE_PATH: Final[str] = "InstallPath"
+REGISTRY_VALUE_EXE: Final[str] = "Executable"
+USERDATA_DIR_NAME: Final[str] = "userdata"
+PLUGINS_DIR_NAME: Final[str] = "plugins"
+DEFAULT_USER_INSTALL: Final[str] = r"Aphelion\Aphelion Editor"
+DEFAULT_MACHINE_INSTALL: Final[str] = r"Aphelion\Aphelion Editor"

aphelion_sdk/host/errors.py

@@ -0,0 +1,20 @@
+"""Errors raised while locating the editor or installing drop-in plugins."""
+
+from __future__ import annotations
+
+
+class EditorHostError(RuntimeError):
+    """Raised when the SDK cannot find or write into Aphelion Editor.
+
+    Parameters:
+        message: Human-readable explanation of what failed.
+
+    Returns:
+        None.
+
+    Exceptions:
+        None.
+
+    Side effects:
+        None.
+    """

aphelion_sdk/host/install.py

@@ -0,0 +1,55 @@
+"""Copy plugin sources into the located editor's user plugin folder."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from aphelion_sdk.host.errors import EditorHostError
+from aphelion_sdk.host.locate import locate_editor
+from aphelion_sdk.host.models import EditorInstall
+from aphelion_sdk.packaging.discovery import plugin_source_files
+from aphelion_sdk.packaging.errors import PluginPackageError
+
+
+def install_plugins_into_editor(
+    source: Path,
+    *,
+    editor: EditorInstall | None = None,
+) -> tuple[Path, ...]:
+    """Copy plugin modules into the editor's ``userdata/plugins`` folder.
+
+    Parameters:
+        source: A ``.py`` file or a directory of plugin modules.
+        editor: Install to target. Defaults to ``locate_editor()``.
+
+    Returns:
+        Destination paths written on disk.
+
+    Exceptions:
+        EditorHostError: If the editor cannot be found or copy fails.
+        PluginPackageError: If ``source`` is not a valid plugin path.
+
+    Side effects:
+        Creates the user plugin directory and overwrites same-named files.
+    """
+    target: EditorInstall = editor if editor is not None else locate_editor()
+    files: tuple[Path, ...] = plugin_source_files(source)
+    destination_dir: Path = target.user_plugin_dir
+    destination_dir.mkdir(parents=True, exist_ok=True)
+    return _copy_plugin_files(files, destination_dir)
+
+
+def _copy_plugin_files(files: tuple[Path, ...], destination_dir: Path) -> tuple[Path, ...]:
+    """Copy each plugin file into ``destination_dir``."""
+    written: list[Path] = []
+    for file_path in files:
+        dest: Path = destination_dir / file_path.name
+        try:
+            shutil.copy2(file_path, dest)
+        except OSError as exc:
+            raise EditorHostError(
+                f"Failed to install {file_path} -> {dest}: {exc}"
+            ) from exc
+        written.append(dest)
+    return tuple(written)