quantum-framework 0.9.0__py3-none-any.whl

quantum/plugins/manifest.py

@@ -0,0 +1,336 @@
+"""
+Quantum Plugin Manifest Parser
+
+Parses quantum-plugin.yaml manifest files that define plugin metadata,
+tag handlers, hooks, and other plugin configuration.
+"""
+
+import yaml
+from pathlib import Path
+from dataclasses import dataclass, field
+from typing import List, Dict, Any, Optional
+
+
+class ManifestError(Exception):
+    """Error parsing or validating plugin manifest"""
+    pass
+
+
+@dataclass
+class TagDefinition:
+    """Defines a custom tag provided by a plugin"""
+    prefix: str           # e.g., "my" for <my:tag>
+    handler: str          # Module path: "src.tags:MyTagHandler"
+    tags: List[str] = field(default_factory=list)  # Optional: specific tags, empty = all
+
+    def __post_init__(self):
+        if not self.prefix:
+            raise ManifestError("Tag definition requires 'prefix'")
+        if not self.handler:
+            raise ManifestError("Tag definition requires 'handler'")
+
+
+@dataclass
+class HookDefinition:
+    """Defines a lifecycle hook registration"""
+    hook_type: str        # before_parse, after_parse, before_render, after_render, etc.
+    handler: str          # Module path: "src.hooks:on_before_render"
+    priority: int = 100   # Lower = earlier execution
+
+    def __post_init__(self):
+        valid_hooks = [
+            'before_parse', 'after_parse',
+            'before_render', 'after_render',
+            'before_execute', 'after_execute',
+            'on_error', 'on_init', 'on_shutdown'
+        ]
+        if self.hook_type not in valid_hooks:
+            raise ManifestError(f"Invalid hook type: {self.hook_type}. Valid: {valid_hooks}")
+
+
+@dataclass
+class AdapterDefinition:
+    """Defines a custom adapter (e.g., for different output targets)"""
+    name: str             # e.g., "my-adapter"
+    handler: str          # Module path: "src.adapters:MyAdapter"
+    target: str = "html"  # Target type: html, textual, desktop, etc.
+
+
+@dataclass
+class CLICommandDefinition:
+    """Defines a custom CLI command"""
+    name: str             # Command name: "my-command"
+    handler: str          # Module path: "src.cli:my_command"
+    help: str = ""        # Help text
+    aliases: List[str] = field(default_factory=list)
+
+
+@dataclass
+class ASTNodeDefinition:
+    """Defines a custom AST node type"""
+    name: str             # Node class name: "MyCustomNode"
+    handler: str          # Module path: "src.nodes:MyCustomNode"
+    base: str = "QuantumNode"  # Base class
+
+
+@dataclass
+class PluginManifest:
+    """
+    Complete plugin manifest from quantum-plugin.yaml
+
+    Example manifest:
+    ```yaml
+    name: my-plugin
+    version: 1.0.0
+    quantum: ">=1.0.0"
+    description: My custom plugin
+    author: Developer Name
+
+    tags:
+      - prefix: "my"
+        handler: "src.tags:MyTagHandler"
+        tags:
+          - custom-tag
+          - another-tag
+
+    hooks:
+      - hook_type: before_render
+        handler: "src.hooks:on_before_render"
+        priority: 50
+
+    adapters:
+      - name: custom-adapter
+        handler: "src.adapters:CustomAdapter"
+        target: html
+
+    cli:
+      - name: generate
+        handler: "src.cli:generate_cmd"
+        help: "Generate custom files"
+
+    nodes:
+      - name: CustomNode
+        handler: "src.nodes:CustomNode"
+
+    dependencies:
+      - other-plugin>=1.0.0
+    ```
+    """
+    name: str
+    version: str
+    quantum_version: str = ">=1.0.0"
+    description: str = ""
+    author: str = ""
+    license: str = ""
+    homepage: str = ""
+    repository: str = ""
+
+    # Plugin components
+    tags: List[TagDefinition] = field(default_factory=list)
+    hooks: List[HookDefinition] = field(default_factory=list)
+    adapters: List[AdapterDefinition] = field(default_factory=list)
+    cli_commands: List[CLICommandDefinition] = field(default_factory=list)
+    nodes: List[ASTNodeDefinition] = field(default_factory=list)
+
+    # Dependencies
+    dependencies: List[str] = field(default_factory=list)
+
+    # Source directory (set during loading)
+    source_path: Optional[Path] = None
+
+    @classmethod
+    def from_file(cls, manifest_path) -> 'PluginManifest':
+        """Load manifest from yaml file"""
+        if isinstance(manifest_path, str):
+            manifest_path = Path(manifest_path)
+        if not manifest_path.exists():
+            raise ManifestError(f"Manifest file not found: {manifest_path}")
+
+        try:
+            with open(manifest_path, 'r', encoding='utf-8') as f:
+                data = yaml.safe_load(f)
+        except yaml.YAMLError as e:
+            raise ManifestError(f"Invalid YAML in manifest: {e}")
+
+        if not data:
+            raise ManifestError("Empty manifest file")
+
+        return cls.from_dict(data, manifest_path.parent)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any], source_path: Path = None) -> 'PluginManifest':
+        """Create manifest from dictionary"""
+        # Validate required fields
+        if 'name' not in data:
+            raise ManifestError("Manifest requires 'name' field")
+        if 'version' not in data:
+            raise ManifestError("Manifest requires 'version' field")
+
+        # Parse tags
+        tags = []
+        for tag_data in data.get('tags', []):
+            if isinstance(tag_data, dict):
+                tags.append(TagDefinition(
+                    prefix=tag_data.get('prefix', ''),
+                    handler=tag_data.get('handler', ''),
+                    tags=tag_data.get('tags', [])
+                ))
+
+        # Parse hooks
+        hooks = []
+        for hook_data in data.get('hooks', []):
+            if isinstance(hook_data, dict):
+                # Support both formats:
+                # - hook_type: before_render
+                #   handler: "src.hooks:fn"
+                # - before_render: "src.hooks:fn"
+                hook_type = hook_data.get('hook_type')
+                handler = hook_data.get('handler')
+                priority = hook_data.get('priority', 100)
+
+                # Alternative format
+                if not hook_type:
+                    for ht in ['before_parse', 'after_parse', 'before_render',
+                               'after_render', 'before_execute', 'after_execute',
+                               'on_error', 'on_init', 'on_shutdown']:
+                        if ht in hook_data:
+                            hook_type = ht
+                            handler = hook_data[ht]
+                            break
+
+                if hook_type and handler:
+                    hooks.append(HookDefinition(
+                        hook_type=hook_type,
+                        handler=handler,
+                        priority=priority
+                    ))
+
+        # Parse adapters
+        adapters = []
+        for adapter_data in data.get('adapters', []):
+            if isinstance(adapter_data, dict):
+                adapters.append(AdapterDefinition(
+                    name=adapter_data.get('name', ''),
+                    handler=adapter_data.get('handler', ''),
+                    target=adapter_data.get('target', 'html')
+                ))
+
+        # Parse CLI commands
+        cli_commands = []
+        for cli_data in data.get('cli', []):
+            if isinstance(cli_data, dict):
+                cli_commands.append(CLICommandDefinition(
+                    name=cli_data.get('name', ''),
+                    handler=cli_data.get('handler', ''),
+                    help=cli_data.get('help', ''),
+                    aliases=cli_data.get('aliases', [])
+                ))
+
+        # Parse AST nodes
+        nodes = []
+        for node_data in data.get('nodes', []):
+            if isinstance(node_data, dict):
+                nodes.append(ASTNodeDefinition(
+                    name=node_data.get('name', ''),
+                    handler=node_data.get('handler', ''),
+                    base=node_data.get('base', 'QuantumNode')
+                ))
+
+        return cls(
+            name=data['name'],
+            version=data['version'],
+            quantum_version=data.get('quantum', '>=1.0.0'),
+            description=data.get('description', ''),
+            author=data.get('author', ''),
+            license=data.get('license', ''),
+            homepage=data.get('homepage', ''),
+            repository=data.get('repository', ''),
+            tags=tags,
+            hooks=hooks,
+            adapters=adapters,
+            cli_commands=cli_commands,
+            nodes=nodes,
+            dependencies=data.get('dependencies', []),
+            source_path=source_path
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert manifest to dictionary"""
+        result = {
+            'name': self.name,
+            'version': self.version,
+            'quantum': self.quantum_version,
+        }
+
+        if self.description:
+            result['description'] = self.description
+        if self.author:
+            result['author'] = self.author
+        if self.license:
+            result['license'] = self.license
+
+        if self.tags:
+            result['tags'] = [
+                {'prefix': t.prefix, 'handler': t.handler, 'tags': t.tags}
+                for t in self.tags
+            ]
+
+        if self.hooks:
+            result['hooks'] = [
+                {'hook_type': h.hook_type, 'handler': h.handler, 'priority': h.priority}
+                for h in self.hooks
+            ]
+
+        if self.adapters:
+            result['adapters'] = [
+                {'name': a.name, 'handler': a.handler, 'target': a.target}
+                for a in self.adapters
+            ]
+
+        if self.cli_commands:
+            result['cli'] = [
+                {'name': c.name, 'handler': c.handler, 'help': c.help, 'aliases': c.aliases}
+                for c in self.cli_commands
+            ]
+
+        if self.nodes:
+            result['nodes'] = [
+                {'name': n.name, 'handler': n.handler, 'base': n.base}
+                for n in self.nodes
+            ]
+
+        if self.dependencies:
+            result['dependencies'] = self.dependencies
+
+        return result
+
+    def validate(self) -> List[str]:
+        """Validate manifest and return list of errors"""
+        errors = []
+
+        # Name validation
+        if not self.name:
+            errors.append("Plugin name is required")
+        elif not self.name.replace('-', '').replace('_', '').isalnum():
+            errors.append(f"Invalid plugin name: {self.name}")
+
+        # Version validation
+        if not self.version:
+            errors.append("Plugin version is required")
+
+        # Tag validation
+        for tag in self.tags:
+            if not tag.prefix:
+                errors.append("Tag prefix is required")
+            if not tag.handler:
+                errors.append(f"Handler is required for tag prefix '{tag.prefix}'")
+
+        # Hook validation
+        for hook in self.hooks:
+            if not hook.handler:
+                errors.append(f"Handler is required for hook '{hook.hook_type}'")
+
+        return errors
+
+    def __repr__(self):
+        return f"<PluginManifest {self.name}@{self.version}>"

quantum/plugins/registry.py

@@ -0,0 +1,371 @@
+"""
+Quantum Plugin Registry
+
+Central registry for all loaded plugins and their components.
+Provides lookup and management for tags, nodes, adapters, and CLI commands.
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Any, Optional, Type, Callable
+from pathlib import Path
+import logging
+
+from .manifest import PluginManifest, TagDefinition, ASTNodeDefinition
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PluginInfo:
+    """Information about a loaded plugin"""
+    name: str
+    version: str
+    manifest: PluginManifest
+    source_path: Path
+    enabled: bool = True
+    loaded_modules: Dict[str, Any] = field(default_factory=dict)
+
+    # Loaded components
+    tag_handlers: Dict[str, Any] = field(default_factory=dict)     # prefix -> handler
+    node_classes: Dict[str, Type] = field(default_factory=dict)    # name -> class
+    adapters: Dict[str, Any] = field(default_factory=dict)         # name -> adapter
+    cli_commands: Dict[str, Callable] = field(default_factory=dict)  # name -> function
+
+    def __repr__(self):
+        status = "enabled" if self.enabled else "disabled"
+        return f"<PluginInfo {self.name}@{self.version} ({status})>"
+
+
+class TagHandler:
+    """
+    Base class for custom tag handlers.
+
+    Plugins should extend this class to handle custom tags.
+
+    Example:
+        class MyTagHandler(TagHandler):
+            prefix = "my"
+
+            def parse(self, element, parser):
+                # Parse XML element into AST node
+                return MyCustomNode(...)
+
+            def execute(self, node, context, runtime):
+                # Execute the node
+                return result
+
+            def render(self, node, renderer):
+                # Render node to HTML
+                return "<div>...</div>"
+    """
+
+    prefix: str = ""  # Tag prefix, e.g., "my" for <my:tag>
+
+    def parse(self, element: Any, parser: Any) -> Any:
+        """
+        Parse XML element into AST node.
+
+        Args:
+            element: XML element (ElementTree Element)
+            parser: Quantum parser instance
+
+        Returns:
+            AST node
+        """
+        raise NotImplementedError("Tag handler must implement parse()")
+
+    def execute(self, node: Any, context: Any, runtime: Any) -> Any:
+        """
+        Execute the AST node.
+
+        Args:
+            node: AST node to execute
+            context: Execution context
+            runtime: Component runtime
+
+        Returns:
+            Execution result
+        """
+        return None
+
+    def render(self, node: Any, renderer: Any) -> str:
+        """
+        Render AST node to HTML.
+
+        Args:
+            node: AST node to render
+            renderer: Renderer instance
+
+        Returns:
+            HTML string
+        """
+        return ""
+
+    def get_supported_tags(self) -> List[str]:
+        """
+        Get list of supported tag names (without prefix).
+
+        Returns:
+            List of tag names, empty list means all tags with this prefix
+        """
+        return []
+
+
+class PluginRegistry:
+    """
+    Central registry for all plugin components.
+
+    Provides lookup and management for:
+    - Plugin manifests and info
+    - Tag handlers by prefix
+    - AST node classes
+    - Adapters
+    - CLI commands
+    """
+
+    def __init__(self):
+        self._plugins: Dict[str, PluginInfo] = {}
+        self._tag_handlers: Dict[str, TagHandler] = {}  # prefix -> handler
+        self._node_classes: Dict[str, Type] = {}        # name -> class
+        self._adapters: Dict[str, Any] = {}             # name -> adapter
+        self._cli_commands: Dict[str, Callable] = {}    # name -> function
+        self._tag_prefixes: Dict[str, str] = {}         # prefix -> plugin_name
+
+    def register_plugin(self, info: PluginInfo) -> None:
+        """
+        Register a loaded plugin.
+
+        Args:
+            info: Plugin information
+        """
+        if info.name in self._plugins:
+            logger.warning(f"Plugin '{info.name}' already registered, replacing")
+
+        self._plugins[info.name] = info
+        logger.info(f"Registered plugin: {info.name}@{info.version}")
+
+    def unregister_plugin(self, name: str) -> bool:
+        """
+        Unregister a plugin and remove all its components.
+
+        Args:
+            name: Plugin name
+
+        Returns:
+            True if plugin was found and removed
+        """
+        if name not in self._plugins:
+            return False
+
+        info = self._plugins[name]
+
+        # Remove tag handlers
+        for prefix in info.tag_handlers:
+            if prefix in self._tag_handlers:
+                del self._tag_handlers[prefix]
+            if prefix in self._tag_prefixes:
+                del self._tag_prefixes[prefix]
+
+        # Remove node classes
+        for node_name in info.node_classes:
+            if node_name in self._node_classes:
+                del self._node_classes[node_name]
+
+        # Remove adapters
+        for adapter_name in info.adapters:
+            if adapter_name in self._adapters:
+                del self._adapters[adapter_name]
+
+        # Remove CLI commands
+        for cmd_name in info.cli_commands:
+            if cmd_name in self._cli_commands:
+                del self._cli_commands[cmd_name]
+
+        del self._plugins[name]
+        logger.info(f"Unregistered plugin: {name}")
+        return True
+
+    def get_plugin(self, name: str) -> Optional[PluginInfo]:
+        """Get plugin info by name"""
+        return self._plugins.get(name)
+
+    def get_all_plugins(self) -> Dict[str, PluginInfo]:
+        """Get all registered plugins"""
+        return self._plugins
+
+    def get_enabled_plugins(self) -> Dict[str, PluginInfo]:
+        """Get only enabled plugins"""
+        return {k: v for k, v in self._plugins.items() if v.enabled}
+
+    # Tag Handler Management
+    def register_tag_handler(self, prefix: str, handler: TagHandler, plugin_name: str) -> None:
+        """
+        Register a tag handler for a prefix.
+
+        Args:
+            prefix: Tag prefix (e.g., "my" for <my:tag>)
+            handler: Tag handler instance
+            plugin_name: Name of the plugin providing this handler
+        """
+        if prefix in self._tag_handlers:
+            logger.warning(f"Tag prefix '{prefix}' already registered by {self._tag_prefixes.get(prefix)}")
+
+        self._tag_handlers[prefix] = handler
+        self._tag_prefixes[prefix] = plugin_name
+
+        # Also add to plugin info
+        if plugin_name in self._plugins:
+            self._plugins[plugin_name].tag_handlers[prefix] = handler
+
+        logger.debug(f"Registered tag handler: {prefix}:* from {plugin_name}")
+
+    def get_tag_handler(self, prefix: str) -> Optional[TagHandler]:
+        """Get tag handler for a prefix"""
+        return self._tag_handlers.get(prefix)
+
+    def has_tag_prefix(self, prefix: str) -> bool:
+        """Check if a tag prefix is registered"""
+        return prefix in self._tag_handlers
+
+    def get_all_tag_prefixes(self) -> List[str]:
+        """Get all registered tag prefixes"""
+        return list(self._tag_handlers.keys())
+
+    # AST Node Management
+    def register_node_class(self, name: str, node_class: Type, plugin_name: str) -> None:
+        """
+        Register a custom AST node class.
+
+        Args:
+            name: Node class name
+            node_class: Node class type
+            plugin_name: Name of the plugin providing this node
+        """
+        self._node_classes[name] = node_class
+
+        if plugin_name in self._plugins:
+            self._plugins[plugin_name].node_classes[name] = node_class
+
+        logger.debug(f"Registered node class: {name} from {plugin_name}")
+
+    def get_node_class(self, name: str) -> Optional[Type]:
+        """Get AST node class by name"""
+        return self._node_classes.get(name)
+
+    def get_all_node_classes(self) -> Dict[str, Type]:
+        """Get all registered node classes"""
+        return self._node_classes
+
+    # Adapter Management
+    def register_adapter(self, name: str, adapter: Any, plugin_name: str) -> None:
+        """
+        Register a custom adapter.
+
+        Args:
+            name: Adapter name
+            adapter: Adapter instance or class
+            plugin_name: Name of the plugin providing this adapter
+        """
+        self._adapters[name] = adapter
+
+        if plugin_name in self._plugins:
+            self._plugins[plugin_name].adapters[name] = adapter
+
+        logger.debug(f"Registered adapter: {name} from {plugin_name}")
+
+    def get_adapter(self, name: str) -> Optional[Any]:
+        """Get adapter by name"""
+        return self._adapters.get(name)
+
+    def get_all_adapters(self) -> Dict[str, Any]:
+        """Get all registered adapters"""
+        return self._adapters
+
+    # CLI Command Management
+    def register_cli_command(
+        self,
+        name: str,
+        handler: Callable,
+        plugin_name: str,
+        aliases: List[str] = None
+    ) -> None:
+        """
+        Register a CLI command.
+
+        Args:
+            name: Command name
+            handler: Command handler function
+            plugin_name: Name of the plugin providing this command
+            aliases: Optional command aliases
+        """
+        self._cli_commands[name] = handler
+
+        # Register aliases
+        for alias in (aliases or []):
+            self._cli_commands[alias] = handler
+
+        if plugin_name in self._plugins:
+            self._plugins[plugin_name].cli_commands[name] = handler
+
+        logger.debug(f"Registered CLI command: {name} from {plugin_name}")
+
+    def get_cli_command(self, name: str) -> Optional[Callable]:
+        """Get CLI command by name"""
+        return self._cli_commands.get(name)
+
+    def get_all_cli_commands(self) -> Dict[str, Callable]:
+        """Get all registered CLI commands"""
+        return self._cli_commands
+
+    # Utility methods
+    def enable_plugin(self, name: str) -> bool:
+        """Enable a plugin"""
+        if name in self._plugins:
+            self._plugins[name].enabled = True
+            return True
+        return False
+
+    def disable_plugin(self, name: str) -> bool:
+        """Disable a plugin"""
+        if name in self._plugins:
+            self._plugins[name].enabled = False
+            return True
+        return False
+
+    def clear(self) -> None:
+        """Clear all registered components"""
+        self._plugins.clear()
+        self._tag_handlers.clear()
+        self._node_classes.clear()
+        self._adapters.clear()
+        self._cli_commands.clear()
+        self._tag_prefixes.clear()
+
+    def get_stats(self) -> Dict[str, int]:
+        """Get registry statistics"""
+        return {
+            'plugins': len(self._plugins),
+            'enabled_plugins': len(self.get_enabled_plugins()),
+            'tag_handlers': len(self._tag_handlers),
+            'node_classes': len(self._node_classes),
+            'adapters': len(self._adapters),
+            'cli_commands': len(self._cli_commands)
+        }
+
+
+# Global registry instance
+_global_registry: Optional[PluginRegistry] = None
+
+
+def get_registry() -> PluginRegistry:
+    """Get the global plugin registry instance"""
+    global _global_registry
+    if _global_registry is None:
+        _global_registry = PluginRegistry()
+    return _global_registry
+
+
+def set_registry(registry: PluginRegistry) -> None:
+    """Set the global plugin registry instance"""
+    global _global_registry
+    _global_registry = registry