pluginforge 0.1.0__tar.gz

pluginforge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Asterios Raptis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pluginforge-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: pluginforge
+Version: 0.1.0
+Summary: Application-agnostic plugin framework built on pluggy
+License: MIT
+License-File: LICENSE
+Keywords: plugin,framework,pluggy,hooks,yaml
+Author: Asterios Raptis
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Provides-Extra: alembic
+Provides-Extra: fastapi
+Requires-Dist: pluggy (>=1.4.0,<2.0.0)
+Requires-Dist: pyyaml (>=6.0,<7.0)
+Project-URL: Repository, https://github.com/astrapi69/pluginforge
+Description-Content-Type: text/markdown
+
+# PluginForge
+
+Application-agnostic Python plugin framework built on [pluggy](https://pluggy.readthedocs.io/).
+
+PluginForge adds the layers that pluggy is missing: YAML configuration, plugin lifecycle management, enable/disable per config, dependency resolution, FastAPI integration, and i18n support.
+
+## Installation
+
+```bash
+pip install pluginforge
+```
+
+With optional FastAPI support:
+
+```bash
+pip install pluginforge[fastapi]
+```
+
+## Quickstart
+
+### 1. Create a plugin
+
+```python
+from pluginforge import BasePlugin
+
+class HelloPlugin(BasePlugin):
+    name = "hello"
+    version = "1.0.0"
+    description = "A hello world plugin"
+
+    def activate(self):
+        print(f"Hello plugin activated with config: {self.config}")
+
+    def get_routes(self):
+        from fastapi import APIRouter
+        router = APIRouter()
+
+        @router.get("/hello")
+        def hello():
+            return {"message": self.config.get("greeting", "Hello!")}
+
+        return [router]
+```
+
+### 2. Configure your app
+
+```yaml
+# config/app.yaml
+app:
+  name: "MyApp"
+  version: "1.0.0"
+  default_language: "en"
+
+plugins:
+  entry_point_group: "myapp.plugins"
+  enabled:
+    - "hello"
+  disabled: []
+```
+
+```yaml
+# config/plugins/hello.yaml
+greeting: "Hello from PluginForge!"
+```
+
+### 3. Use PluginManager
+
+```python
+from pluginforge import PluginManager
+
+pm = PluginManager("config/app.yaml")
+
+# Register plugins directly (or use entry points for auto-discovery)
+pm.register_plugins([HelloPlugin])
+
+# Access plugins
+for plugin in pm.get_active_plugins():
+    print(f"Active: {plugin.name} v{plugin.version}")
+
+# Mount FastAPI routes
+from fastapi import FastAPI
+app = FastAPI()
+pm.mount_routes(app)  # Routes at /api/plugins/{name}/
+```
+
+## Features
+
+- **YAML Configuration** - App config, per-plugin config, and i18n strings
+- **Plugin Lifecycle** - init, activate, deactivate with error handling
+- **Enable/Disable** - Control plugins via config lists
+- **Dependency Resolution** - Topological sorting with circular dependency detection
+- **FastAPI Integration** - Auto-mount plugin routes under `/api/plugins/{name}/`
+- **Alembic Support** - Collect migration directories from plugins
+- **i18n** - Multi-language strings from YAML with fallback
+
+## Entry Point Discovery
+
+Register plugins as entry points in your `pyproject.toml`:
+
+```toml
+[project.entry-points."myapp.plugins"]
+hello = "myapp.plugins.hello:HelloPlugin"
+```
+
+Then use `discover_plugins()` instead of `register_plugins()`:
+
+```python
+pm = PluginManager("config/app.yaml")
+pm.discover_plugins()  # Auto-discovers from entry points
+```
+
+## i18n
+
+```yaml
+# config/i18n/en.yaml
+common:
+  save: "Save"
+  cancel: "Cancel"
+```
+
+```python
+pm.get_text("common.save", "en")  # "Save"
+pm.get_text("common.save", "de")  # "Speichern"
+```
+
+## Development
+
+```bash
+# Install dependencies
+poetry install --with dev
+
+# Run tests
+poetry run pytest
+
+# Lint
+poetry run ruff check pluginforge/ tests/
+
+# Format
+poetry run ruff format pluginforge/ tests/
+```
+
+## License
+
+MIT
+

pluginforge-0.1.0/README.md

@@ -0,0 +1,144 @@
+# PluginForge
+
+Application-agnostic Python plugin framework built on [pluggy](https://pluggy.readthedocs.io/).
+
+PluginForge adds the layers that pluggy is missing: YAML configuration, plugin lifecycle management, enable/disable per config, dependency resolution, FastAPI integration, and i18n support.
+
+## Installation
+
+```bash
+pip install pluginforge
+```
+
+With optional FastAPI support:
+
+```bash
+pip install pluginforge[fastapi]
+```
+
+## Quickstart
+
+### 1. Create a plugin
+
+```python
+from pluginforge import BasePlugin
+
+class HelloPlugin(BasePlugin):
+    name = "hello"
+    version = "1.0.0"
+    description = "A hello world plugin"
+
+    def activate(self):
+        print(f"Hello plugin activated with config: {self.config}")
+
+    def get_routes(self):
+        from fastapi import APIRouter
+        router = APIRouter()
+
+        @router.get("/hello")
+        def hello():
+            return {"message": self.config.get("greeting", "Hello!")}
+
+        return [router]
+```
+
+### 2. Configure your app
+
+```yaml
+# config/app.yaml
+app:
+  name: "MyApp"
+  version: "1.0.0"
+  default_language: "en"
+
+plugins:
+  entry_point_group: "myapp.plugins"
+  enabled:
+    - "hello"
+  disabled: []
+```
+
+```yaml
+# config/plugins/hello.yaml
+greeting: "Hello from PluginForge!"
+```
+
+### 3. Use PluginManager
+
+```python
+from pluginforge import PluginManager
+
+pm = PluginManager("config/app.yaml")
+
+# Register plugins directly (or use entry points for auto-discovery)
+pm.register_plugins([HelloPlugin])
+
+# Access plugins
+for plugin in pm.get_active_plugins():
+    print(f"Active: {plugin.name} v{plugin.version}")
+
+# Mount FastAPI routes
+from fastapi import FastAPI
+app = FastAPI()
+pm.mount_routes(app)  # Routes at /api/plugins/{name}/
+```
+
+## Features
+
+- **YAML Configuration** - App config, per-plugin config, and i18n strings
+- **Plugin Lifecycle** - init, activate, deactivate with error handling
+- **Enable/Disable** - Control plugins via config lists
+- **Dependency Resolution** - Topological sorting with circular dependency detection
+- **FastAPI Integration** - Auto-mount plugin routes under `/api/plugins/{name}/`
+- **Alembic Support** - Collect migration directories from plugins
+- **i18n** - Multi-language strings from YAML with fallback
+
+## Entry Point Discovery
+
+Register plugins as entry points in your `pyproject.toml`:
+
+```toml
+[project.entry-points."myapp.plugins"]
+hello = "myapp.plugins.hello:HelloPlugin"
+```
+
+Then use `discover_plugins()` instead of `register_plugins()`:
+
+```python
+pm = PluginManager("config/app.yaml")
+pm.discover_plugins()  # Auto-discovers from entry points
+```
+
+## i18n
+
+```yaml
+# config/i18n/en.yaml
+common:
+  save: "Save"
+  cancel: "Cancel"
+```
+
+```python
+pm.get_text("common.save", "en")  # "Save"
+pm.get_text("common.save", "de")  # "Speichern"
+```
+
+## Development
+
+```bash
+# Install dependencies
+poetry install --with dev
+
+# Run tests
+poetry run pytest
+
+# Lint
+poetry run ruff check pluginforge/ tests/
+
+# Format
+poetry run ruff format pluginforge/ tests/
+```
+
+## License
+
+MIT

pluginforge-0.1.0/pluginforge/__init__.py

@@ -0,0 +1,8 @@
+"""PluginForge - Application-agnostic plugin framework built on pluggy."""
+
+from pluginforge.base import BasePlugin
+from pluginforge.discovery import CircularDependencyError
+from pluginforge.manager import PluginManager
+
+__version__ = "0.1.0"
+__all__ = ["BasePlugin", "CircularDependencyError", "PluginManager"]

pluginforge-0.1.0/pluginforge/alembic_ext.py

@@ -0,0 +1,33 @@
+"""Alembic migration support for plugins."""
+
+import logging
+from pathlib import Path
+
+from pluginforge.base import BasePlugin
+
+logger = logging.getLogger(__name__)
+
+
+def collect_migrations_dirs(plugins: list[BasePlugin]) -> dict[str, str]:
+    """Collect Alembic migration directories from all plugins.
+
+    Args:
+        plugins: List of active plugins.
+
+    Returns:
+        Dict mapping plugin name to migrations directory path.
+    """
+    migrations: dict[str, str] = {}
+    for plugin in plugins:
+        migrations_dir = plugin.get_migrations_dir()
+        if migrations_dir is None:
+            continue
+        path = Path(migrations_dir)
+        if not path.is_dir():
+            logger.warning(
+                "Plugin '%s' migrations dir does not exist: %s", plugin.name, migrations_dir
+            )
+            continue
+        migrations[plugin.name] = str(path)
+        logger.info("Collected migrations for plugin '%s': %s", plugin.name, migrations_dir)
+    return migrations

pluginforge-0.1.0/pluginforge/base.py

@@ -0,0 +1,57 @@
+"""Base plugin class for all PluginForge plugins."""
+
+from abc import ABC
+from typing import Any
+
+
+class BasePlugin(ABC):
+    """Abstract base class for all PluginForge plugins.
+
+    Attributes:
+        name: Unique plugin identifier (e.g. "export").
+        version: Plugin version string.
+        api_version: Hook spec compatibility version.
+        description: Human-readable description.
+        author: Plugin author.
+        depends_on: List of plugin names this plugin depends on.
+        config: Plugin configuration, populated during init().
+    """
+
+    name: str
+    version: str = "0.1.0"
+    api_version: str = "1"
+    description: str = ""
+    author: str = ""
+    depends_on: list[str] = []
+    config: dict[str, Any] = {}
+
+    def init(self, app_config: dict[str, Any], plugin_config: dict[str, Any]) -> None:
+        """Called when the plugin is loaded. Receives app and plugin config.
+
+        Args:
+            app_config: The global application configuration.
+            plugin_config: Plugin-specific configuration from YAML.
+        """
+        self.config = plugin_config
+
+    def activate(self) -> None:
+        """Called when the plugin is activated."""
+
+    def deactivate(self) -> None:
+        """Called when the plugin is deactivated. Release resources here."""
+
+    def get_routes(self) -> list:
+        """Return FastAPI routers to be mounted. Optional.
+
+        Returns:
+            List of FastAPI APIRouter instances.
+        """
+        return []
+
+    def get_migrations_dir(self) -> str | None:
+        """Return path to Alembic migration scripts. Optional.
+
+        Returns:
+            Path string or None if no migrations.
+        """
+        return None

pluginforge-0.1.0/pluginforge/config.py

@@ -0,0 +1,71 @@
+"""YAML configuration loading and merging."""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+
+def load_yaml(path: str | Path) -> dict[str, Any]:
+    """Load a YAML file and return its contents as a dict.
+
+    Args:
+        path: Path to the YAML file.
+
+    Returns:
+        Parsed YAML content, or empty dict if file is missing or empty.
+    """
+    path = Path(path)
+    if not path.exists():
+        logger.debug("Config file not found, using empty defaults: %s", path)
+        return {}
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+        return data if isinstance(data, dict) else {}
+    except yaml.YAMLError as e:
+        logger.warning("Failed to parse YAML file %s: %s", path, e)
+        return {}
+
+
+def load_app_config(config_path: str | Path) -> dict[str, Any]:
+    """Load the main application config.
+
+    Args:
+        config_path: Path to app.yaml.
+
+    Returns:
+        Application configuration dict.
+    """
+    return load_yaml(config_path)
+
+
+def load_plugin_config(config_dir: str | Path, plugin_name: str) -> dict[str, Any]:
+    """Load plugin-specific configuration from config/plugins/{name}.yaml.
+
+    Args:
+        config_dir: Base config directory (parent of plugins/).
+        plugin_name: Name of the plugin.
+
+    Returns:
+        Plugin configuration dict.
+    """
+    path = Path(config_dir) / "plugins" / f"{plugin_name}.yaml"
+    return load_yaml(path)
+
+
+def load_i18n(config_dir: str | Path, lang: str) -> dict[str, Any]:
+    """Load i18n strings for a specific language.
+
+    Args:
+        config_dir: Base config directory (parent of i18n/).
+        lang: Language code (e.g. "en", "de").
+
+    Returns:
+        i18n strings dict.
+    """
+    path = Path(config_dir) / "i18n" / f"{lang}.yaml"
+    return load_yaml(path)

pluginforge-0.1.0/pluginforge/discovery.py

@@ -0,0 +1,124 @@
+"""Plugin discovery via entry points and dependency resolution."""
+
+import logging
+from importlib.metadata import entry_points
+from typing import Any
+
+from pluginforge.base import BasePlugin
+
+logger = logging.getLogger(__name__)
+
+
+class CircularDependencyError(Exception):
+    """Raised when a circular dependency is detected among plugins."""
+
+
+def discover_entry_points(group: str) -> dict[str, type[BasePlugin]]:
+    """Load plugin classes from entry points.
+
+    Args:
+        group: Entry point group name (e.g. "myapp.plugins").
+
+    Returns:
+        Dict mapping plugin name to plugin class.
+    """
+    plugins: dict[str, type[BasePlugin]] = {}
+    eps = entry_points()
+    group_eps = eps.select(group=group) if hasattr(eps, "select") else eps.get(group, [])
+    for ep in group_eps:
+        try:
+            plugin_cls = ep.load()
+            if hasattr(plugin_cls, "name"):
+                plugins[plugin_cls.name] = plugin_cls
+            else:
+                logger.warning("Entry point %s has no 'name' attribute, skipping", ep.name)
+        except Exception as e:
+            logger.error("Failed to load entry point %s: %s", ep.name, e)
+    return plugins
+
+
+def filter_plugins(
+    plugins: dict[str, type[BasePlugin]],
+    enabled: list[str] | None,
+    disabled: list[str] | None,
+) -> dict[str, type[BasePlugin]]:
+    """Filter plugins based on enabled/disabled lists.
+
+    If enabled list is provided, only those plugins are kept.
+    Disabled list always takes precedence (plugins in disabled are removed).
+
+    Args:
+        plugins: All discovered plugins.
+        enabled: List of enabled plugin names, or None for all.
+        disabled: List of disabled plugin names, or None.
+
+    Returns:
+        Filtered plugins dict.
+    """
+    if enabled is not None:
+        plugins = {name: cls for name, cls in plugins.items() if name in enabled}
+    if disabled:
+        plugins = {name: cls for name, cls in plugins.items() if name not in disabled}
+    return plugins
+
+
+def resolve_dependencies(
+    plugins: dict[str, Any],
+) -> list[str]:
+    """Topologically sort plugins by their dependencies.
+
+    Args:
+        plugins: Dict mapping plugin name to plugin class (must have depends_on attribute).
+
+    Returns:
+        List of plugin names in dependency order.
+
+    Raises:
+        CircularDependencyError: If circular dependencies are detected.
+    """
+    graph: dict[str, list[str]] = {}
+    for name, cls in plugins.items():
+        deps = getattr(cls, "depends_on", []) or []
+        graph[name] = [d for d in deps if d in plugins]
+
+    visited: set[str] = set()
+    in_stack: set[str] = set()
+    order: list[str] = []
+
+    def visit(node: str) -> None:
+        if node in in_stack:
+            raise CircularDependencyError(f"Circular dependency detected involving plugin '{node}'")
+        if node in visited:
+            return
+        in_stack.add(node)
+        for dep in graph.get(node, []):
+            visit(dep)
+        in_stack.remove(node)
+        visited.add(node)
+        order.append(node)
+
+    for name in graph:
+        visit(name)
+
+    return order
+
+
+def check_missing_dependencies(
+    plugins: dict[str, Any],
+) -> dict[str, list[str]]:
+    """Check which plugins have unresolved dependencies.
+
+    Args:
+        plugins: Dict mapping plugin name to plugin class.
+
+    Returns:
+        Dict mapping plugin name to list of missing dependency names.
+    """
+    missing: dict[str, list[str]] = {}
+    available = set(plugins.keys())
+    for name, cls in plugins.items():
+        deps = getattr(cls, "depends_on", []) or []
+        unresolved = [d for d in deps if d not in available]
+        if unresolved:
+            missing[name] = unresolved
+    return missing

pluginforge-0.1.0/pluginforge/fastapi_ext.py

@@ -0,0 +1,37 @@
+"""FastAPI integration for mounting plugin routes."""
+
+import logging
+
+from pluginforge.base import BasePlugin
+
+logger = logging.getLogger(__name__)
+
+
+def mount_plugin_routes(app: "object", plugins: list[BasePlugin]) -> None:
+    """Mount routes from all plugins onto a FastAPI app.
+
+    Each plugin's routes are mounted under /api/plugins/{plugin_name}/.
+
+    Args:
+        app: A FastAPI application instance.
+        plugins: List of active plugins.
+    """
+    try:
+        from fastapi import FastAPI
+    except ImportError:
+        raise ImportError(
+            "FastAPI is required for route mounting. "
+            "Install it with: pip install pluginforge[fastapi]"
+        )
+
+    if not isinstance(app, FastAPI):
+        raise TypeError(f"Expected FastAPI instance, got {type(app).__name__}")
+
+    for plugin in plugins:
+        routes = plugin.get_routes()
+        if not routes:
+            continue
+        for router in routes:
+            prefix = f"/api/plugins/{plugin.name}"
+            app.include_router(router, prefix=prefix)
+            logger.info("Mounted routes for plugin '%s' at %s", plugin.name, prefix)

pluginforge-0.1.0/pluginforge/i18n.py

@@ -0,0 +1,82 @@
+"""Internationalization support via YAML files."""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from pluginforge.config import load_i18n
+
+logger = logging.getLogger(__name__)
+
+
+class I18n:
+    """Manages internationalized strings loaded from YAML files.
+
+    Attributes:
+        config_dir: Base config directory containing i18n/ folder.
+        default_lang: Fallback language code.
+    """
+
+    def __init__(self, config_dir: str | Path, default_lang: str = "en") -> None:
+        self.config_dir = Path(config_dir)
+        self.default_lang = default_lang
+        self._strings: dict[str, dict[str, Any]] = {}
+
+    def load_language(self, lang: str) -> None:
+        """Load strings for a language if not already loaded.
+
+        Args:
+            lang: Language code (e.g. "en", "de").
+        """
+        if lang not in self._strings:
+            self._strings[lang] = load_i18n(self.config_dir, lang)
+
+    def get_text(self, key: str, lang: str | None = None) -> str:
+        """Get a translated string by dot-notation key.
+
+        Falls back to default language if key is not found in requested language.
+        Returns the key itself if not found in any language.
+
+        Args:
+            key: Dot-notation key (e.g. "common.save").
+            lang: Language code, or None for default.
+
+        Returns:
+            Translated string, or the key if not found.
+        """
+        lang = lang or self.default_lang
+        self.load_language(lang)
+
+        value = self._resolve_key(key, lang)
+        if value is not None:
+            return value
+
+        if lang != self.default_lang:
+            self.load_language(self.default_lang)
+            value = self._resolve_key(key, self.default_lang)
+            if value is not None:
+                return value
+
+        logger.debug("i18n key not found: %s (lang=%s)", key, lang)
+        return key
+
+    def _resolve_key(self, key: str, lang: str) -> str | None:
+        """Resolve a dot-notation key in a language's strings.
+
+        Args:
+            key: Dot-notation key.
+            lang: Language code.
+
+        Returns:
+            The resolved string or None.
+        """
+        data = self._strings.get(lang, {})
+        parts = key.split(".")
+        for part in parts:
+            if isinstance(data, dict):
+                data = data.get(part)
+            else:
+                return None
+            if data is None:
+                return None
+        return str(data) if not isinstance(data, dict) else None

pluginforge-0.1.0/pluginforge/lifecycle.py

@@ -0,0 +1,124 @@
+"""Plugin lifecycle management (init, activate, deactivate)."""
+
+import logging
+from typing import Any
+
+from pluginforge.base import BasePlugin
+
+logger = logging.getLogger(__name__)
+
+
+class PluginLifecycle:
+    """Manages plugin lifecycle transitions.
+
+    Tracks which plugins are initialized and active, handles
+    init/activate/deactivate calls with error handling.
+    """
+
+    def __init__(self) -> None:
+        self._initialized: dict[str, BasePlugin] = {}
+        self._active: dict[str, BasePlugin] = {}
+
+    def init_plugin(
+        self,
+        plugin: BasePlugin,
+        app_config: dict[str, Any],
+        plugin_config: dict[str, Any],
+    ) -> bool:
+        """Initialize a plugin with config.
+
+        Args:
+            plugin: The plugin instance to initialize.
+            app_config: Global application config.
+            plugin_config: Plugin-specific config.
+
+        Returns:
+            True if initialization succeeded, False otherwise.
+        """
+        try:
+            plugin.init(app_config, plugin_config)
+            self._initialized[plugin.name] = plugin
+            logger.info("Initialized plugin: %s", plugin.name)
+            return True
+        except Exception as e:
+            logger.error("Failed to initialize plugin %s: %s", plugin.name, e)
+            return False
+
+    def activate_plugin(self, plugin: BasePlugin) -> bool:
+        """Activate an initialized plugin.
+
+        Args:
+            plugin: The plugin instance to activate.
+
+        Returns:
+            True if activation succeeded, False otherwise.
+        """
+        if plugin.name not in self._initialized:
+            logger.warning("Cannot activate uninitialized plugin: %s", plugin.name)
+            return False
+        try:
+            plugin.activate()
+            self._active[plugin.name] = plugin
+            logger.info("Activated plugin: %s", plugin.name)
+            return True
+        except Exception as e:
+            logger.error("Failed to activate plugin %s: %s", plugin.name, e)
+            return False
+
+    def deactivate_plugin(self, plugin: BasePlugin) -> bool:
+        """Deactivate an active plugin.
+
+        Args:
+            plugin: The plugin instance to deactivate.
+
+        Returns:
+            True if deactivation succeeded, False otherwise.
+        """
+        if plugin.name not in self._active:
+            logger.warning("Cannot deactivate inactive plugin: %s", plugin.name)
+            return False
+        try:
+            plugin.deactivate()
+            del self._active[plugin.name]
+            logger.info("Deactivated plugin: %s", plugin.name)
+            return True
+        except Exception as e:
+            logger.error("Failed to deactivate plugin %s: %s", plugin.name, e)
+            return False
+
+    def deactivate_all(self) -> None:
+        """Deactivate all active plugins in reverse activation order."""
+        names = list(reversed(list(self._active.keys())))
+        for name in names:
+            plugin = self._active[name]
+            self.deactivate_plugin(plugin)
+
+    def get_active_plugins(self) -> list[BasePlugin]:
+        """Return list of currently active plugins.
+
+        Returns:
+            List of active BasePlugin instances.
+        """
+        return list(self._active.values())
+
+    def get_plugin(self, name: str) -> BasePlugin | None:
+        """Get an initialized plugin by name.
+
+        Args:
+            name: Plugin name.
+
+        Returns:
+            The plugin instance or None.
+        """
+        return self._initialized.get(name)
+
+    def is_active(self, name: str) -> bool:
+        """Check if a plugin is currently active.
+
+        Args:
+            name: Plugin name.
+
+        Returns:
+            True if the plugin is active.
+        """
+        return name in self._active

pluginforge-0.1.0/pluginforge/manager.py

@@ -0,0 +1,243 @@
+"""Central PluginManager that orchestrates config, discovery, lifecycle, and hooks."""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import pluggy
+
+from pluginforge.base import BasePlugin
+from pluginforge.config import load_app_config, load_plugin_config
+from pluginforge.discovery import (
+    CircularDependencyError,
+    check_missing_dependencies,
+    discover_entry_points,
+    filter_plugins,
+    resolve_dependencies,
+)
+from pluginforge.i18n import I18n
+from pluginforge.lifecycle import PluginLifecycle
+
+logger = logging.getLogger(__name__)
+
+
+class PluginManager:
+    """Central manager for plugin discovery, lifecycle, and hooks.
+
+    Wraps pluggy.PluginManager and adds YAML config, lifecycle management,
+    dependency resolution, and i18n support.
+
+    Args:
+        config_path: Path to app.yaml configuration file.
+    """
+
+    def __init__(self, config_path: str = "config/app.yaml") -> None:
+        self._config_path = Path(config_path)
+        self._config_dir = self._config_path.parent
+        self._app_config = load_app_config(self._config_path)
+
+        plugins_config = self._app_config.get("plugins", {})
+        group = plugins_config.get("entry_point_group", "pluginforge.plugins")
+        self._entry_point_group = group
+
+        self._pm = pluggy.PluginManager(group)
+        self._lifecycle = PluginLifecycle()
+
+        default_lang = self._app_config.get("app", {}).get("default_language", "en")
+        self._i18n = I18n(self._config_dir, default_lang=default_lang)
+
+    def get_app_config(self) -> dict[str, Any]:
+        """Return the loaded application configuration.
+
+        Returns:
+            App config dict.
+        """
+        return self._app_config
+
+    def get_plugin_config(self, plugin_name: str) -> dict[str, Any]:
+        """Load and return config for a specific plugin.
+
+        Args:
+            plugin_name: Name of the plugin.
+
+        Returns:
+            Plugin configuration dict.
+        """
+        return load_plugin_config(self._config_dir, plugin_name)
+
+    def discover_plugins(self) -> None:
+        """Discover, filter, resolve dependencies, and activate plugins.
+
+        Loads plugins from entry points, filters by enabled/disabled config,
+        checks dependencies, sorts topologically, then initializes and
+        activates each plugin.
+        """
+        plugins = discover_entry_points(self._entry_point_group)
+
+        plugins_config = self._app_config.get("plugins", {})
+        enabled = plugins_config.get("enabled")
+        disabled = plugins_config.get("disabled")
+        plugins = filter_plugins(plugins, enabled, disabled)
+
+        missing = check_missing_dependencies(plugins)
+        for name, deps in missing.items():
+            logger.warning("Plugin '%s' has missing dependencies %s, skipping", name, deps)
+            del plugins[name]
+
+        try:
+            order = resolve_dependencies(plugins)
+        except CircularDependencyError as e:
+            raise e
+
+        for name in order:
+            cls = plugins[name]
+            plugin = cls()
+            plugin_config = self.get_plugin_config(name)
+
+            if not self._lifecycle.init_plugin(plugin, self._app_config, plugin_config):
+                continue
+
+            self._pm.register(plugin, name=name)
+
+            if not self._lifecycle.activate_plugin(plugin):
+                self._pm.unregister(name=name)
+
+    def register_plugins(self, plugin_classes: list[type[BasePlugin]]) -> None:
+        """Register plugin classes directly (without entry point discovery).
+
+        Useful for testing or programmatic plugin registration.
+
+        Args:
+            plugin_classes: List of plugin classes to register.
+        """
+        plugins_map: dict[str, type[BasePlugin]] = {}
+        for cls in plugin_classes:
+            plugins_map[cls.name] = cls
+
+        plugins_config = self._app_config.get("plugins", {})
+        enabled = plugins_config.get("enabled")
+        disabled = plugins_config.get("disabled")
+        plugins_map = filter_plugins(plugins_map, enabled, disabled)
+
+        missing = check_missing_dependencies(plugins_map)
+        for name, deps in missing.items():
+            logger.warning("Plugin '%s' has missing dependencies %s, skipping", name, deps)
+            del plugins_map[name]
+
+        order = resolve_dependencies(plugins_map)
+
+        for name in order:
+            cls = plugins_map[name]
+            plugin = cls()
+            plugin_config = self.get_plugin_config(name)
+
+            if not self._lifecycle.init_plugin(plugin, self._app_config, plugin_config):
+                continue
+
+            self._pm.register(plugin, name=name)
+
+            if not self._lifecycle.activate_plugin(plugin):
+                self._pm.unregister(name=name)
+
+    def activate_plugin(self, name: str) -> None:
+        """Activate a specific initialized plugin.
+
+        Args:
+            name: Plugin name.
+        """
+        plugin = self._lifecycle.get_plugin(name)
+        if plugin is None:
+            logger.warning("Plugin '%s' not found", name)
+            return
+        self._lifecycle.activate_plugin(plugin)
+
+    def deactivate_plugin(self, name: str) -> None:
+        """Deactivate a specific active plugin.
+
+        Args:
+            name: Plugin name.
+        """
+        plugin = self._lifecycle.get_plugin(name)
+        if plugin is None:
+            logger.warning("Plugin '%s' not found", name)
+            return
+        self._lifecycle.deactivate_plugin(plugin)
+
+    def get_plugin(self, name: str) -> BasePlugin | None:
+        """Get a plugin instance by name.
+
+        Args:
+            name: Plugin name.
+
+        Returns:
+            Plugin instance or None.
+        """
+        return self._lifecycle.get_plugin(name)
+
+    def get_active_plugins(self) -> list[BasePlugin]:
+        """Return all currently active plugins.
+
+        Returns:
+            List of active plugins.
+        """
+        return self._lifecycle.get_active_plugins()
+
+    def deactivate_all(self) -> None:
+        """Deactivate all active plugins in reverse order."""
+        self._lifecycle.deactivate_all()
+
+    def register_hookspecs(self, spec_module: object) -> None:
+        """Register hook specifications from a module.
+
+        Args:
+            spec_module: Module containing hookspec-decorated functions.
+        """
+        self._pm.add_hookspecs(spec_module)
+
+    def call_hook(self, hook_name: str, **kwargs: Any) -> list[Any]:
+        """Call a named hook on all registered plugins.
+
+        Args:
+            hook_name: Name of the hook to call.
+            **kwargs: Arguments to pass to hook implementations.
+
+        Returns:
+            List of results from all hook implementations.
+        """
+        hook = getattr(self._pm.hook, hook_name, None)
+        if hook is None:
+            logger.warning("Hook '%s' not found", hook_name)
+            return []
+        return hook(**kwargs)
+
+    def mount_routes(self, app: object) -> None:
+        """Mount FastAPI routes from all active plugins.
+
+        Args:
+            app: A FastAPI application instance.
+        """
+        from pluginforge.fastapi_ext import mount_plugin_routes
+
+        mount_plugin_routes(app, self.get_active_plugins())
+
+    def get_text(self, key: str, lang: str | None = None) -> str:
+        """Get an internationalized string.
+
+        Args:
+            key: Dot-notation i18n key.
+            lang: Language code, or None for default.
+
+        Returns:
+            Translated string.
+        """
+        return self._i18n.get_text(key, lang)
+
+    def collect_migrations(self) -> dict[str, str]:
+        """Collect Alembic migration directories from all active plugins.
+
+        Returns:
+            Dict mapping plugin name to migrations directory path.
+        """
+        from pluginforge.alembic_ext import collect_migrations_dirs
+
+        return collect_migrations_dirs(self.get_active_plugins())

pluginforge-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[tool.poetry]
+name = "pluginforge"
+version = "0.1.0"
+description = "Application-agnostic plugin framework built on pluggy"
+authors = ["Asterios Raptis"]
+license = "MIT"
+readme = "README.md"
+repository = "https://github.com/astrapi69/pluginforge"
+keywords = ["plugin", "framework", "pluggy", "hooks", "yaml"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+packages = [{ include = "pluginforge" }]
+
+[tool.poetry.dependencies]
+python = "^3.11"
+pluggy = "^1.4.0"
+pyyaml = "^6.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+pytest-cov = "^5.0"
+ruff = "^0.4"
+
+[tool.poetry.extras]
+fastapi = ["fastapi"]
+alembic = ["alembic", "sqlalchemy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=pluginforge --cov-report=term-missing"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"