maqet 0.0.1.4__py3-none-any.whl → 0.0.5__py3-none-any.whl

maqet/generators/python_generator.py

@@ -0,0 +1,247 @@
+"""
+Python API Generator
+
+Provides clean Python API access to decorated methods.
+"""
+
+import inspect
+from typing import Any, Dict, Optional
+
+from ..api import APIMethodMetadata, APIRegistry
+from .base_generator import BaseGenerator
+
+
+class PythonAPIGenerator(BaseGenerator):
+    """
+    Provides programmatic access to @api_method decorated methods.
+
+    This generator enables clean Python API usage where methods can be
+    called directly with proper validation and error handling.
+    """
+
+    def __init__(self, maqet_instance: Any, registry: APIRegistry):
+        """
+        Initialize Python API generator.
+
+        Args:
+            maqet_instance: Instance of Maqet class
+            registry: API registry containing method metadata
+        """
+        super().__init__(maqet_instance, registry)
+
+    def generate(self) -> "PythonAPIInterface":
+        """
+        Generate Python API interface.
+
+        Returns:
+            Python API interface object
+        """
+        return PythonAPIInterface(self.maqet_instance, self.registry)
+
+    def execute_method(self, method_name: str, *args, **kwargs) -> Any:
+        """
+        Execute a method by name with validation.
+
+        Args:
+            method_name: Name of method to execute
+            *args: Positional arguments
+            **kwargs: Keyword arguments
+
+        Returns:
+            Method execution result
+
+        Raises:
+            ValueError: If method not found or invalid parameters
+            TypeError: If parameter types are incorrect
+        """
+        # Get method metadata
+        metadata = self.get_method_by_name(method_name)
+        if not metadata:
+            raise ValueError(f"Method '{method_name}' not found")
+
+        # Convert positional args to kwargs for validation
+        combined_kwargs = self._combine_args_kwargs(metadata, args, kwargs)
+
+        # Validate parameters
+        self._validate_parameters(metadata, combined_kwargs)
+
+        # Get the actual method from the instance
+        method = getattr(self.maqet_instance, method_name)
+
+        # Execute method with original args and kwargs
+        return method(*args, **kwargs)
+
+    def _validate_parameters(
+        self, metadata: APIMethodMetadata, kwargs: Dict[str, Any]
+    ) -> None:
+        """
+        Validate method parameters.
+
+        Args:
+            metadata: Method metadata
+            kwargs: Parameters provided by user
+
+        Raises:
+            ValueError: If required parameters missing or unknown parameters provided
+        """
+        # Check for missing required parameters
+        missing = self.validate_required_parameters(metadata, kwargs)
+        if missing:
+            raise ValueError(
+                f"Missing required parameters: {', '.join(missing)}"
+            )
+
+        # Check for unknown parameters only if there's no **kwargs parameter
+        has_var_keyword = any(
+            param.kind == inspect.Parameter.VAR_KEYWORD
+            for param in metadata.parameters.values()
+        )
+
+        if not has_var_keyword:
+            valid_params = set(metadata.parameters.keys())
+            provided_params = set(kwargs.keys())
+            unknown = provided_params - valid_params
+            if unknown:
+                raise ValueError(f"Unknown parameters: {', '.join(unknown)}")
+
+        # Type validation could be added here if needed
+
+    def _combine_args_kwargs(
+        self, metadata: APIMethodMetadata, args: tuple, kwargs: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Combine positional and keyword arguments into a single kwargs dict for validation.
+
+        Args:
+            metadata: Method metadata
+            args: Positional arguments
+            kwargs: Keyword arguments
+
+        Returns:
+            Combined arguments as kwargs dict
+
+        Raises:
+            ValueError: If too many positional arguments provided
+        """
+        combined = kwargs.copy()
+
+        # Get parameter names in order (excluding 'self')
+        param_names = list(metadata.parameters.keys())
+
+        # Map positional args to parameter names
+        if len(args) > len(param_names):
+            raise ValueError(
+                f"Too many positional arguments: expected {len(param_names)}, got {len(args)}"
+            )
+
+        for i, arg_value in enumerate(args):
+            param_name = param_names[i]
+            if param_name in combined:
+                raise ValueError(
+                    f"Parameter '{param_name}' specified both positionally and as keyword argument"
+                )
+            combined[param_name] = arg_value
+
+        return combined
+
+
+class PythonAPIInterface:
+    """
+    Dynamic Python API interface that provides direct method access.
+
+    This class dynamically creates methods based on registered API methods,
+    allowing for clean Python usage like:
+
+        api = PythonAPIInterface(maqet_instance, registry)
+        api.start("myvm", detach=True)
+        api.stop("myvm")
+    """
+
+    def __init__(self, maqet_instance: Any, registry: APIRegistry):
+        """
+        Initialize Python API interface.
+
+        Args:
+            maqet_instance: Instance of Maqet class
+            registry: API registry containing method metadata
+        """
+        self.maqet_instance = maqet_instance
+        self.registry = registry
+        self.generator = PythonAPIGenerator(maqet_instance, registry)
+
+    def __getattr__(self, name: str) -> Any:
+        """
+        Dynamically provide access to API methods.
+
+        Args:
+            name: Method name
+
+        Returns:
+            Callable method
+
+        Raises:
+            AttributeError: If method not found
+        """
+        # Check if this is a registered API method
+        metadata = self.generator.get_method_by_name(name)
+        if metadata:
+            return lambda *args, **kwargs: self.generator.execute_method(
+                name, *args, **kwargs
+            )
+
+        # Check if it's a direct attribute on the instance
+        if hasattr(self.maqet_instance, name):
+            return getattr(self.maqet_instance, name)
+
+        raise AttributeError(
+            f"'{self.__class__.__name__}' object has no attribute '{name}'"
+        )
+
+    def list_methods(self) -> Dict[str, str]:
+        """
+        List all available API methods.
+
+        Returns:
+            Dictionary mapping method names to descriptions
+        """
+        methods = {}
+        for metadata in self.registry.get_all_methods():
+            if metadata.owner_class == self.maqet_instance.__class__.__name__:
+                methods[metadata.name] = metadata.description
+        return methods
+
+    def get_method_help(self, method_name: str) -> Optional[str]:
+        """
+        Get help text for a method.
+
+        Args:
+            method_name: Method name
+
+        Returns:
+            Help text or None if method not found
+        """
+        metadata = self.generator.get_method_by_name(method_name)
+        if not metadata:
+            return None
+
+        help_text = f"{metadata.name}: {metadata.description}\n\n"
+
+        # Add parameters
+        if metadata.parameters:
+            help_text += "Parameters:\n"
+            for param_name, param in metadata.parameters.items():
+                required = param.default == param.empty
+                default_text = (
+                    f" (default: {param.default})"
+                    if not required
+                    else " (required)"
+                )
+                help_text += f"  {param_name}{default_text}\n"
+
+        # Add examples
+        if metadata.examples:
+            help_text += "\nExamples:\n"
+            for example in metadata.examples:
+                help_text += f"  {example}\n"
+
+        return help_text.strip()

maqet/generators/rest_generator.py

@@ -0,0 +1,58 @@
+"""
+REST API Generator (Placeholder)
+
+This is a placeholder showing how the API system can be extended with new generators.
+A REST API generator could be implemented here using FastAPI, Flask, or similar.
+
+Example implementation would:
+1. Inherit from BaseGenerator
+2. Read method metadata from API_REGISTRY
+3. Generate REST routes with proper HTTP methods:
+   - GET /api/vms/{vm_id}/status -> status(vm_id)
+   - POST /api/vms -> add(config, name)
+   - DELETE /api/vms/{vm_id} -> rm(vm_id)
+4. Handle request/response serialization
+5. Add authentication/authorization if needed
+
+Usage:
+    from maqet.generators import RestAPIGenerator
+    generator = RestAPIGenerator(maqet_instance, API_REGISTRY)
+    app = generator.generate()  # Returns FastAPI/Flask app
+"""
+
+from ..api import APIRegistry
+from .base_generator import BaseGenerator
+
+
+class RestAPIGenerator(BaseGenerator):
+    """
+    Placeholder REST API generator demonstrating extensibility.
+
+    A real implementation would generate REST endpoints from @api_method
+    decorated methods, handling routing, serialization, and validation.
+    """
+
+    def generate(self):
+        """
+        Generate REST API routes.
+
+        Returns:
+            Web application instance (FastAPI, Flask, etc.)
+        """
+        raise NotImplementedError(
+            "REST API generation not yet implemented. "
+            "This is a placeholder demonstrating the extensible architecture."
+        )
+
+    def run(self, host: str = "0.0.0.0", port: int = 8000):
+        """
+        Run the REST API server.
+
+        Args:
+            host: Server host
+            port: Server port
+        """
+        raise NotImplementedError(
+            "REST API server not yet implemented. "
+            "This would start a web server with generated routes."
+        )

maqet/handlers/__init__.py

@@ -0,0 +1,12 @@
+"""
+MAQET handlers package.
+
+Contains base handler classes and specific handlers for configuration
+initialization and stage execution.
+"""
+
+from .base import Handler
+from .init import InitHandler
+from .stage import StageHandler
+
+__all__ = ["Handler", "InitHandler", "StageHandler"]

maqet/handlers/base.py

@@ -0,0 +1,108 @@
+import inspect
+from abc import ABC
+from typing import Callable
+
+from benedict import benedict
+
+from maqet.logger import LOG
+
+
+class HandlerError(Exception):
+    """
+    Handler error
+    """
+
+
+class Handler(ABC):
+    """
+    Interface for Maqet state processors
+    """
+    __METHODS = {}
+
+    @classmethod
+    def method(self, function: Callable, **kwargs):
+        """
+        Decorator to add method to handler methods
+        """
+        name = kwargs.get('name', function.__name__)
+        handler_name = self.__name__
+        if handler_name not in self.__METHODS:
+            self.__METHODS[handler_name] = {}
+
+        self.__METHODS[handler_name][name] = function
+
+        # TODO: add signature check:
+        # method(state: dict, *args, **kwargs)
+
+        def stub(*args, **kwargs):
+            raise HandlerError("Handler method called outside of handler")
+
+        return stub
+
+    def __init__(self, state: dict,
+                 argument: list | dict | str,
+                 *args, **kwargs):
+
+        self.state = benedict(state)
+        self.error_fatal = kwargs.get('error_fatal', False)
+
+        self.__execute(argument)
+
+    def __execute(self, argument: list | dict | str):
+        if isinstance(argument, list):
+            LOG.debug(f"Argument {argument} - splitting into subarguments")
+            for subargument in argument:
+                self.__execute(subargument)
+        elif isinstance(argument, dict):
+            LOG.debug(f"Argument {argument} - running by key-value")
+            for method_name, subargument in argument.items():
+                self.__call_method(method_name, subargument)
+        elif isinstance(argument, str):
+            LOG.debug(f"Argument {argument} - running without argument")
+            self.__call_method(argument, None)
+        else:
+            self.__fail("Type check error"
+                        f" {argument} is not list | dict | str")
+
+    @classmethod
+    def method_exists(self, method_name: str) -> bool:
+        if method_name not in self.__METHODS[self.__name__]:
+            LOG.debug(f"{self.__name__}::{method_name} not exists")
+            return False
+        LOG.debug(f"{self.__name__}::{method_name} exists")
+        return True
+
+    @classmethod
+    def get_methods(self) -> list:
+        return self.__METHODS[self.__name__].keys()
+
+    def __call_method(self,
+                      method_name: str,
+                      argument: list | dict | str = None):
+
+        if not self.method_exists(method_name):
+            self.__fail(f"Method '{method_name}' not available"
+                        f" in {self.__class__.__name__}")
+        method = self.__METHODS[self.__class__.__name__].get(method_name)
+
+        LOG.debug(f"Inspecting signature for {method_name}: {inspect.signature(method)}")
+        LOG.debug(f"{self.__class__.__name__}::"
+                  f"{method.__name__}({str(argument)})")
+        try:
+            if isinstance(argument, list):
+                method(self.state, *argument)
+            elif isinstance(argument, dict):
+                method(self.state, **argument)
+            elif argument is None:
+                method(self.state)
+            else:
+                method(self.state, argument)
+        except Exception as exc:
+            msg = f"{method_name}({argument}) execution error\n{exc}\n"
+            self.__fail(msg)
+
+    def __fail(self, msg: str):
+        if self.error_fatal:
+            raise HandlerError(msg)
+        else:
+            LOG.error(msg)

maqet/handlers/init.py

@@ -0,0 +1,147 @@
+from benedict import benedict
+
+from maqet.handlers.base import Handler
+# from maqet.handlers.stage import PipelineHandler as run_pipeline
+from maqet.handlers.stage import StageHandler
+from maqet.logger import LOG
+from maqet.qemu_args import Arguments
+# Legacy import - Drive class no longer exists in current storage.py
+# from maqet.storage import Drive
+
+
+class InitHandler(Handler):
+    """
+    Handles full config of maqet (basically yaml)
+    """
+
+
+@InitHandler.method
+def binary(state, binary: str):
+    LOG.debug(f'Setting binary: {binary}')
+    state.binary = binary
+
+
+@InitHandler.method
+def arguments(state, *args):
+    LOG.debug(f'Setting arguments: {args}')
+    state['const_args'] = Arguments.parse_args(*args)
+
+
+@InitHandler.method
+def plain_arguments(state, *args):
+    LOG.debug(f'Setting plain arguments: {args}')
+    if 'const_args' not in state:
+        state['const_args'] = []
+    state['const_args'] += Arguments.split_args(*args)
+
+
+@InitHandler.method
+def storage(state, *args):
+    if 'storage' not in state:
+        state.storage = {}
+
+    if 'const_args' not in state:
+        state.const_args = []
+
+    for drive in args:
+        n = 0
+        name = drive.get('name', f"drive{n}")
+        while name in state.storage:
+            n += 1
+            name = f"drive{n}"
+
+        # Legacy code - Drive class no longer exists
+        # state.storage[name] = Drive(**drive)
+        state.storage[name] = drive  # Store config dict for now
+
+    # Legacy code - commented out as Drive class no longer exists
+    # for name, drive in state.storage.items():
+    #     state.const_args += drive()
+
+
+@InitHandler.method
+def parameters(state, **kwargs):
+    LOG.debug(f'Setting parameters: {kwargs}')
+    if len(kwargs) == 0:
+        return
+    state.parameters = kwargs
+
+
+@InitHandler.method
+def serial(state, *args):
+    LOG.debug(f'Setting serial: {args}')
+    state.serial = args
+
+
+@InitHandler.method
+def pipeline(state, **kwargs):
+    default_stage = {'idle': {'tasks': [
+        'launch',
+        {'wait_for_input': {'prompt': 'Press ENTER to finish'}},
+    ]}}
+
+    state.pipeline = []
+    state.procedures = []
+
+    stages = kwargs.get('stages', {})
+
+    if len(state._stages_to_run) == 0:
+        state.pipeline.append(default_stage)
+        LOG.info("Stage idle (default) added to current pipeline")
+        return
+
+    # pre_pipeline_tasks = kwargs.get('pre_pipeline_tasks', [])
+    # post_pipeline_tasks = kwargs.get('post_pipeline_tasks', [])
+    # pre_stage_tasks = kwargs.get('pre_stage_tasks', [])
+    # post_stage_tasks = kwargs.get('post_stage_tasks', [])
+
+    procedures = kwargs.get('procedures', {})
+    state.procedures.append(procedures)
+    # data._stages_to_run += ['_pre_pipeline_tasks', '_post_pipeline_tasks']
+
+    for name, stage in stages.items():
+        current_stage = stage
+        current_tasks = []
+
+        # stage.tasks = pre_stage_tasks + stage.tasks + post_stage_tasks
+
+        if name not in state._stages_to_run:
+            continue
+        if 'tasks' not in stage or len(stage['tasks']) == 0:
+            LOG.warn(f'Stage {name} incorrect, no tasks found. Skipping')
+            continue
+
+        # TODO: procedure that uses another procedure
+        for task in stage['tasks']:
+            if isinstance(task, dict):
+                task_name = next(iter(task))
+                if task_name == 'procedure':
+                    if task['procedure'] in procedures:
+                        current_tasks += procedures[task['procedure']]
+                        LOG.debug(f"Procedure {task['procedure']}"
+                                  " added to stage")
+                    else:
+                        raise Exception(f"Procedure {task['procedure']}"
+                                        " not found in procedures")
+                else:
+                    current_tasks.append(task)
+                    LOG.debug(f"Task {task_name} added to stage")
+            else:
+                current_tasks.append(task)
+                LOG.debug(f"Task {task} added to stage")
+
+        for task in current_tasks:
+            if isinstance(task, dict):
+                task = next(iter(task))
+            if not StageHandler.method_exists(task):
+                LOG.error(f"Task {task} not validated")
+                raise Exception(f"Task {task} is invalid")
+            LOG.debug(f"Task {task} validated")
+
+        current_stage['tasks'] = current_tasks
+        current_stage['arguments'] = Arguments.parse_args(
+            *stage.get('arguments', [])
+        ) + stage.get('plain_arguments', [])
+
+        state.pipeline.append({name: current_stage})
+        LOG.info(f"Stage {name} added to current pipeline")