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

maqet/api/registry.py

@@ -0,0 +1,182 @@
+"""
+API Registry
+
+Registry for tracking all decorated API methods and providing
+lookup capabilities for CLI and Python API generation.
+
+Supports both global registry (backward compatibility) and instance-based
+registry (for parallel tests and multiple Maqet instances).
+"""
+
+import inspect
+from typing import Any, Dict, List, Optional
+
+from .metadata import APIMethodMetadata
+
+
+class APIRegistry:
+    """
+    Registry for API methods decorated with @api_method.
+
+    This registry enables generators to discover all available methods
+    and their metadata for creating CLI commands and Python APIs.
+
+    Can be used as:
+    - Global registry (API_REGISTRY) for backward compatibility
+    - Instance registry (one per Maqet instance) for isolated registries
+    """
+
+    def __init__(self):
+        """Initialize the API registry with empty collections."""
+        self._methods: Dict[str, APIMethodMetadata] = {}
+        self._cli_commands: Dict[str, str] = {}  # cli_name -> full_name
+        self._categories: Dict[str, List[str]] = {}  # category -> [full_names]
+
+    def register(self, metadata: APIMethodMetadata) -> None:
+        """
+        Register a new API method.
+
+        Args:
+            metadata: Method metadata to register
+        """
+        full_name = metadata.full_name
+        self._methods[full_name] = metadata
+
+        # Register CLI command mapping
+        if metadata.cli_name:
+            self._cli_commands[metadata.cli_name] = full_name
+
+        # Register category mapping
+        if metadata.category not in self._categories:
+            self._categories[metadata.category] = []
+        self._categories[metadata.category].append(full_name)
+
+    def get_method(self, full_name: str) -> Optional[APIMethodMetadata]:
+        """
+        Get method metadata by full name.
+
+        Args:
+            full_name: Full method name (e.g., 'Maqet.start')
+
+        Returns:
+            Method metadata or None if not found
+        """
+        return self._methods.get(full_name)
+
+    def get_by_cli_name(self, cli_name: str) -> Optional[APIMethodMetadata]:
+        """
+        Get method metadata by CLI command name.
+
+        Args:
+            cli_name: CLI command name (e.g., 'start')
+
+        Returns:
+            Method metadata or None if not found
+        """
+        full_name = self._cli_commands.get(cli_name)
+        return self._methods.get(full_name) if full_name else None
+
+    def get_by_category(self, category: str) -> List[APIMethodMetadata]:
+        """
+        Get all methods in a category.
+
+        Args:
+            category: Category name (e.g., 'vm', 'qmp')
+
+        Returns:
+            List of method metadata in the category
+        """
+        full_names = self._categories.get(category, [])
+        return [self._methods[name] for name in full_names]
+
+    def get_all_methods(self) -> List[APIMethodMetadata]:
+        """
+        Get all registered methods.
+
+        Returns:
+            List of all method metadata
+        """
+        return list(self._methods.values())
+
+    def get_all_methods_dict(self) -> Dict[str, APIMethodMetadata]:
+        """
+        Get all registered methods as a dictionary.
+
+        Returns:
+            Dictionary mapping method names to metadata
+        """
+        return self._methods.copy()
+
+    def get_all_cli_commands(self) -> Dict[str, APIMethodMetadata]:
+        """
+        Get all CLI commands and their metadata.
+
+        Returns:
+            Dictionary mapping CLI command names to metadata
+        """
+        return {
+            cli_name: self._methods[full_name]
+            for cli_name, full_name in self._cli_commands.items()
+        }
+
+    def get_categories(self) -> List[str]:
+        """
+        Get all available categories.
+
+        Returns:
+            List of category names
+        """
+        return list(self._categories.keys())
+
+    def clear(self) -> None:
+        """Clear all registered methods (mainly for testing)."""
+        self._methods.clear()
+        self._cli_commands.clear()
+        self._categories.clear()
+
+    def register_from_instance(self, instance: Any) -> None:
+        """
+        Register all @api_method decorated methods from an instance.
+
+        This enables instance-based registries where each Maqet instance
+        has its own registry, allowing for:
+        - Parallel test execution without registry pollution
+        - Multiple Maqet instances with different configurations
+        - Thread-safe operation
+
+        Args:
+            instance: Object instance to scan for @api_method decorated methods
+
+        Example:
+            registry = APIRegistry()
+            maqet = Maqet()
+            registry.register_from_instance(maqet)
+        """
+        # Get the class of the instance
+        cls = instance.__class__
+
+        # Scan for decorated methods
+        for name, method in inspect.getmembers(cls, predicate=inspect.isfunction):
+            if hasattr(method, "_api_metadata"):
+                metadata: APIMethodMetadata = method._api_metadata
+                # Clone metadata with bound method (instance-specific)
+                bound_metadata = APIMethodMetadata(
+                    name=metadata.name,
+                    function=getattr(instance, name),  # Bound method
+                    owner_class=metadata.owner_class,
+                    cli_name=metadata.cli_name,
+                    description=metadata.description,
+                    signature=metadata.signature,
+                    category=metadata.category,
+                    requires_vm=metadata.requires_vm,
+                    examples=metadata.examples,
+                    aliases=metadata.aliases,
+                    hidden=metadata.hidden,
+                    parent=metadata.parent,
+                )
+                self.register(bound_metadata)
+
+
+# Global registry instance (for backward compatibility)
+# New code should prefer instance-based registries via register_from_instance()
+API_REGISTRY = APIRegistry()

maqet/cli.py

@@ -0,0 +1,71 @@
+import argparse
+import os
+from pathlib import Path
+
+from benedict import benedict
+
+from maqet.logger import LOG, configure_file_logging
+from maqet.maqet import Maqet
+
+
+def cli():
+    LOG.debug("Maqet CLI started")
+    parser = argparse.ArgumentParser(
+        prog="MAQET - m4x0n QEMU Tool",
+        description="Using YAML file for running QEMU VM and automate actions",
+        epilog="Still in development"
+    )
+
+    parser.add_argument(
+        "-f", "--file",
+        type=Path,
+        help="yaml with config"  # TODO: Write more
+    )
+    parser.add_argument(
+        "stages",
+        nargs="*",
+        help="stages to run. If not stated - just start VM",
+    )
+    parser.add_argument(
+        "-v", "--verbose",
+        action='count',
+        help="increase verbose level",
+        default=0
+    )
+    parser.add_argument(
+        "-a", "--argument",
+        nargs="*",
+        help="Plain arguments to pass to qemu,"
+        "use with quotes: -a '-arg_a ... -arg_z' "
+    )
+
+
+    cli_args = parser.parse_args()
+
+    # Set console handler level based on verbosity, but leave file handler at DEBUG
+    console_handler = LOG.handlers[0]
+    console_handler.setLevel(50 - cli_args.verbose * 10 if cli_args.verbose < 5 else 10)
+
+    if cli_args.file is not None:
+        os.chdir(cli_args.file.parent)
+        raw_config = benedict.from_yaml(cli_args.file.name)
+        # NOTE: should rise Exception if yaml incorrect
+    else:
+        raw_config = benedict({})
+
+    if 'log_file' in raw_config:
+        configure_file_logging(raw_config['log_file'])
+
+    raw_config.plain_arguments = cli_args.argument
+
+    LOG.debug(f"CLI Arguments: {cli_args}")
+
+    maqet = Maqet(*cli_args.stages, **raw_config)
+    LOG.debug(f"Maqet initialized, stages to run: {cli_args.stages}")
+    maqet()
+    LOG.debug("Maqet finished")
+
+
+def main():
+    """Entry point for the maqet command."""
+    cli()

maqet/config/__init__.py

@@ -0,0 +1,26 @@
+"""
+MAQET Configuration Module
+
+Dynamic configuration parsing and validation system using decorators.
+"""
+
+from .merger import ConfigError, ConfigMerger
+from .parser import ConfigParser
+from .validators import (
+    ConfigValidationError,
+    config_validator,
+    get_required_keys,
+    get_validators,
+    validate_config_data,
+)
+
+__all__ = [
+    "ConfigError",
+    "ConfigMerger",
+    "ConfigParser",
+    "ConfigValidationError",
+    "config_validator",
+    "get_validators",
+    "get_required_keys",
+    "validate_config_data",
+]

maqet/config/merger.py

@@ -0,0 +1,237 @@
+"""
+Configuration Merger
+
+Handles deep-merging of multiple configuration files.
+Provides utilities for loading and merging YAML configuration files
+with deep merge support for complex nested structures.
+"""
+
+from pathlib import Path
+from typing import Any, Dict, List, Union
+
+import yaml
+
+
+class ConfigError(Exception):
+    """Configuration parsing errors"""
+
+
+class ConfigMerger:
+    """
+    Handles deep-merging of multiple configuration files.
+
+    Provides utilities for loading and merging YAML configuration files
+    with deep merge support for complex nested structures.
+    """
+
+    @staticmethod
+    def _merge_arguments_list(
+        base_args: List[Any], override_args: List[Any]
+    ) -> List[Any]:
+        """
+        Merge two arguments lists with override behavior.
+
+        For arguments like [{foo: 0}, {bar: 10}] and [{bar: 20}, {baz: 30}],
+        later configs override earlier ones by key, producing:
+        [{foo: 0}, {bar: 20}, {baz: 30}]
+
+        Args:
+            base_args: Base arguments list
+            override_args: Override arguments list
+
+        Returns:
+            Merged arguments list with overrides applied
+        """
+        # Track arguments by their keys (for dict items)
+        # Use dict to maintain insertion order (Python 3.7+)
+        merged = {}
+
+        # Process base arguments first
+        for arg in base_args:
+            if isinstance(arg, dict):
+                # For dict items, use the key as identifier
+                for key in arg.keys():
+                    merged[key] = arg
+            else:
+                # For non-dict items (strings), use the item itself as key
+                merged[str(arg)] = arg
+
+        # Process override arguments (later configs win)
+        for arg in override_args:
+            if isinstance(arg, dict):
+                # Override or add dict items by key
+                for key in arg.keys():
+                    merged[key] = arg
+            else:
+                # Override or add non-dict items
+                merged[str(arg)] = arg
+
+        # Convert back to list, preserving order
+        return list(merged.values())
+
+    @staticmethod
+    def deep_merge(
+        base: Dict[str, Any], override: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Deep merge two dictionaries.
+
+        Args:
+            base: Base configuration dictionary
+            override: Override configuration dictionary
+
+        Returns:
+            Deep-merged configuration dictionary
+        """
+        result = base.copy()
+
+        for key, value in override.items():
+            if (
+                key in result
+                and isinstance(result[key], dict)
+                and isinstance(value, dict)
+            ):
+                # Recursively merge nested dictionaries
+                result[key] = ConfigMerger.deep_merge(result[key], value)
+            elif (
+                key in result
+                and isinstance(result[key], list)
+                and isinstance(value, list)
+            ):
+                # Special handling for 'arguments' list: merge dict items by key
+                if key == "arguments":
+                    result[key] = ConfigMerger._merge_arguments_list(
+                        result[key], value
+                    )
+                else:
+                    # For other lists (storage, etc.), concatenate
+                    # This allows adding storage devices, network interfaces, etc.
+                    result[key] = result[key] + value
+            else:
+                # Override scalar values and non-dict types
+                result[key] = value
+
+        return result
+
+    @staticmethod
+    def _resolve_relative_paths(
+        config_data: Dict[str, Any], config_dir: Path
+    ) -> Dict[str, Any]:
+        """
+        Resolve relative file paths in config to absolute paths.
+
+        Layer 3 of automatic path resolution: resolve paths relative to config file location.
+        This makes configs portable and allows relative paths like ./live.iso to work.
+
+        Args:
+            config_data: Configuration dictionary
+            config_dir: Directory containing the config file
+
+        Returns:
+            Configuration with resolved absolute paths
+        """
+        # Resolve storage device file paths
+        if "storage" in config_data and isinstance(
+            config_data["storage"], list
+        ):
+            for storage_item in config_data["storage"]:
+                if isinstance(storage_item, dict) and "file" in storage_item:
+                    file_path = storage_item["file"]
+                    if not Path(file_path).is_absolute():
+                        # Resolve relative to config file directory
+                        storage_item["file"] = str(
+                            (config_dir / file_path).resolve()
+                        )
+
+                # Resolve VirtFS path entries
+                if isinstance(storage_item, dict) and "path" in storage_item:
+                    path_value = storage_item["path"]
+                    if not Path(path_value).is_absolute():
+                        storage_item["path"] = str(
+                            (config_dir / path_value).resolve()
+                        )
+
+        # Resolve file paths in arguments (drive file=./path,...)
+        if "arguments" in config_data and isinstance(
+            config_data["arguments"], list
+        ):
+            for arg_item in config_data["arguments"]:
+                if isinstance(arg_item, dict):
+                    for key, value in arg_item.items():
+                        if isinstance(value, str) and "file=" in value:
+                            # Parse drive argument: file=./live.iso,media=cdrom
+                            parts = value.split(",")
+                            for i, part in enumerate(parts):
+                                if part.startswith("file="):
+                                    file_path = part[
+                                        5:
+                                    ]  # Remove 'file=' prefix
+                                    if not Path(file_path).is_absolute():
+                                        abs_path = str(
+                                            (config_dir / file_path).resolve()
+                                        )
+                                        parts[i] = f"file={abs_path}"
+                            arg_item[key] = ",".join(parts)
+
+        return config_data
+
+    @staticmethod
+    def load_and_merge_files(
+        config_files: Union[str, List[str]],
+    ) -> Dict[str, Any]:
+        """
+        Load and merge multiple configuration files.
+
+        Args:
+            config_files: Single config file path or list of config file paths
+
+        Returns:
+            Merged configuration data
+
+        Raises:
+            ConfigError: If any config file cannot be loaded or parsed
+        """
+        if isinstance(config_files, str):
+            config_files = [config_files]
+
+        if not config_files:
+            return {}
+
+        merged_config = {}
+
+        for config_file in config_files:
+            config_path = Path(config_file)
+            if not config_path.exists():
+                raise ConfigError(
+                    f"Configuration file not found: {config_file}"
+                )
+
+            try:
+                with open(config_path) as f:
+                    config_data = yaml.safe_load(f) or {}
+
+                if not isinstance(config_data, dict):
+                    raise ConfigError(
+                        f"Configuration in {config_file} must be a "
+                        f"YAML dictionary"
+                    )
+
+                # Layer 3: Resolve relative paths in config relative to config file location
+                config_dir = config_path.parent.resolve()
+                config_data = ConfigMerger._resolve_relative_paths(
+                    config_data, config_dir
+                )
+
+                # Deep merge with previous configs
+                merged_config = ConfigMerger.deep_merge(
+                    merged_config, config_data
+                )
+
+            except yaml.YAMLError as e:
+                raise ConfigError(f"Invalid YAML in {config_file}: {e}")
+            except Exception as e:
+                raise ConfigError(
+                    f"Error loading configuration from {config_file}: {e}"
+                )
+
+        return merged_config