aphelion-plugin-sdk 0.1.0__tar.gz

aphelion_plugin_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,97 @@
+# 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/aphelion_plugin_sdk.egg-info/PKG-INFO

@@ -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/aphelion_plugin_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,42 @@
+README.md
+pyproject.toml
+aphelion_plugin_sdk.egg-info/PKG-INFO
+aphelion_plugin_sdk.egg-info/SOURCES.txt
+aphelion_plugin_sdk.egg-info/dependency_links.txt
+aphelion_plugin_sdk.egg-info/entry_points.txt
+aphelion_plugin_sdk.egg-info/requires.txt
+aphelion_plugin_sdk.egg-info/top_level.txt
+aphelion_sdk/__init__.py
+aphelion_sdk/__main__.py
+aphelion_sdk/plugin.py
+aphelion_sdk/properties.py
+aphelion_sdk/py.typed
+aphelion_sdk/registration.py
+aphelion_sdk/types.py
+aphelion_sdk/version.py
+aphelion_sdk/audio/__init__.py
+aphelion_sdk/cli/__init__.py
+aphelion_sdk/cli/main.py
+aphelion_sdk/host/__init__.py
+aphelion_sdk/host/constants.py
+aphelion_sdk/host/errors.py
+aphelion_sdk/host/install.py
+aphelion_sdk/host/locate.py
+aphelion_sdk/host/models.py
+aphelion_sdk/host/validate.py
+aphelion_sdk/host/windows.py
+aphelion_sdk/packaging/__init__.py
+aphelion_sdk/packaging/builder.py
+aphelion_sdk/packaging/discovery.py
+aphelion_sdk/packaging/errors.py
+aphelion_sdk/packaging/names.py
+aphelion_sdk/packaging/project.py
+aphelion_sdk/video/__init__.py
+aphelion_sdk/video/effect.py
+aphelion_sdk/widgets/__init__.py
+aphelion_sdk/widgets/base.py
+aphelion_sdk/widgets/dialog.py
+aphelion_sdk/widgets/host.py
+aphelion_sdk/widgets/kinds.py
+aphelion_sdk/widgets/panel.py
+aphelion_sdk/widgets/qt.py

aphelion_plugin_sdk-0.1.0/aphelion_plugin_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aphelion_plugin_sdk-0.1.0/aphelion_plugin_sdk.egg-info/entry_points.txt

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

aphelion_plugin_sdk-0.1.0/aphelion_plugin_sdk.egg-info/requires.txt

@@ -0,0 +1,6 @@
+numpy>=1.26.0
+
+[dev]
+build>=1.2.0
+pytest>=8.0.0
+mypy>=1.8.0

aphelion_plugin_sdk-0.1.0/aphelion_plugin_sdk.egg-info/top_level.txt

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

aphelion_plugin_sdk-0.1.0/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_plugin_sdk-0.1.0/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_plugin_sdk-0.1.0/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_plugin_sdk-0.1.0/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"]