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

maqet/__init__.py

@@ -1,7 +1,51 @@
-from .core import Drive, Machine, Maqet
+"""
+> LESS MARKETING, MORE FACTS!.
 
-__all__ = (
-    'Drive',
-    'Machine',
-    'Maqet',
-)
+MAQET - M4x0n's QEMU Tool
+
+A revolutionary VM management system implementing unified API generation architecture.
+
+MAQET transforms traditional VM management by providing a "write once, generate everywhere"
+approach where single @api_method decorated methods automatically become:
+- CLI commands (maqet <command>)
+- Python API methods (maqet.method())
+- Configuration-driven calls (YAML key → method execution)
+
+Key Features:
+- Zero duplication: One method definition serves all interfaces
+- Type-safe validation across CLI and Python APIs
+- SQLite state management with XDG directory compliance
+- Complete VM lifecycle management (add, start, stop, rm, etc.)
+- QMP integration for VM control
+- Production-ready for dependent projects
+
+Quick Start:
+    # CLI usage
+    $ maqet add config.yaml --name myvm
+    $ maqet start myvm --detach
+
+    # Python API usage
+    from maqet import Maqet
+    maqet = Maqet()
+    vm_id = maqet.add(name='myvm', memory='4G')
+    maqet.start(vm_id, detach=True)
+
+    # Configuration-driven usage
+    add: {name: 'myvm', memory: '4G'}
+    start: {vm_id: 'myvm', detach: true}
+
+Architecture:
+The unified API system consists of:
+- @api_method decorator for metadata capture
+- APIRegistry for tracking decorated methods
+- Generators for creating interfaces (CLI, Python, Config)
+- StateManager for persistent VM state
+- Machine class for QEMU integration
+"""
+
+from .api import api_method
+from .maqet import Maqet, MaqetError
+from .state import StateManager, VMInstance
+
+__version__ = "0.0.5"
+__all__ = ["Maqet", "MaqetError", "StateManager", "VMInstance", "api_method"]

maqet/__main__.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""
+MAQET CLI Entry Point.
+
+Main CLI interface that uses the unified API generation system.
+"""
+
+import json
+import sys
+import traceback
+from enum import IntEnum
+
+from .__version__ import __version__
+from .maqet import Maqet
+
+
+class ExitCode(IntEnum):
+    """Exit code constants for MAQET CLI."""
+
+    SUCCESS = 0
+    ERROR = 1
+    INTERRUPTED = 2
+    INVALID_CONFIG = 3
+
+
+def main():
+    """Execute the main CLI entry point."""
+    # Check for --version flag first (before creating Maqet instance)
+    if "--version" in sys.argv or "-V" in sys.argv:
+        print(f"MAQET version {__version__}")
+        return ExitCode.SUCCESS
+
+    # Check for debug mode - this enables full tracebacks on errors
+    # Note: --debug is different from -v/--verbose which controls log verbosity
+    # --debug affects error reporting, -v affects logging levels
+    debug_mode = "--debug" in sys.argv
+    if debug_mode:
+        sys.argv.remove("--debug")
+
+    # Check for output format
+    output_format = "auto"
+    if "--format" in sys.argv:
+        idx = sys.argv.index("--format")
+        if idx + 1 < len(sys.argv):
+            output_format = sys.argv[idx + 1]
+            sys.argv.pop(idx)  # Remove --format
+            sys.argv.pop(idx)  # Remove format value
+
+    try:
+        maqet = Maqet()
+        result = maqet.cli()
+
+        # Handle CLI output based on format
+        _format_output(result, output_format)
+
+        return ExitCode.SUCCESS
+
+    except KeyboardInterrupt:
+        print("\nInterrupted by user", file=sys.stderr)
+        sys.exit(ExitCode.INTERRUPTED)
+
+    except Exception as e:
+        if debug_mode:
+            # Print full traceback in debug mode
+            print("\n=== Debug Traceback ===", file=sys.stderr)
+            traceback.print_exc()
+            print("=" * 23, file=sys.stderr)
+        else:
+            print(f"Error: {e}", file=sys.stderr)
+            print("Run with --debug for full traceback", file=sys.stderr)
+        sys.exit(ExitCode.ERROR)
+
+
+def _format_output(result, format_type: str = "auto"):
+    """
+    Format and print output using FormatterFactory.
+
+    Args:
+        result: Result data to format
+        format_type: Output format (auto, json, yaml, plain, table)
+    """
+    if result is None:
+        return
+
+    from .formatters import FormatterFactory
+
+    try:
+        formatter = FormatterFactory.create(format_type)
+        formatter.format(result)
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(ExitCode.ERROR)
+
+
+if __name__ == "__main__":
+    main()

maqet/__version__.py

@@ -0,0 +1,3 @@
+"""Version information for MAQET."""
+
+__version__ = "0.0.5"

maqet/api/__init__.py

@@ -0,0 +1,35 @@
+"""
+MAQET API System
+
+This module implements the unified API generation system that allows
+single method definitions to automatically become CLI commands, Python API
+methods, REST API endpoints, GraphQL resolvers, and other interfaces.
+
+The system is designed to be extensible - new generators can be added by:
+1. Implementing BaseGenerator interface in generators/
+2. Reading method metadata from API_REGISTRY
+3. Generating appropriate interface code (routes, schemas, etc.)
+
+Example generators:
+- CLIGenerator: Creates argparse CLI commands
+- PythonAPIGenerator: Creates direct Python method calls
+- RestAPIGenerator: Could create FastAPI/Flask routes
+- GraphQLGenerator: Could create GraphQL schema and resolvers
+- OpenAPIGenerator: Could generate OpenAPI/Swagger documentation
+"""
+
+from .decorators import AutoRegisterAPI, api_method, register_class_methods
+from .metadata import APIMethodMetadata
+from .registry import API_REGISTRY, APIRegistry
+
+__all__ = [
+    "api_method",
+    "register_class_methods",
+    "AutoRegisterAPI",
+    "API_REGISTRY",
+    "APIRegistry",
+    "APIMethodMetadata",
+]
+
+# NOTE: The system is designed to be easily extensible for new interfaces.
+# See module docstring above for implementation guidance.

maqet/api/decorators.py

@@ -0,0 +1,184 @@
+"""
+API Method Decorator.
+
+The @api_method decorator is the core of MAQET's unified API generation system.
+It captures method metadata to enable automatic CLI and Python API generation.
+"""
+
+import inspect
+from functools import wraps
+from typing import Callable, List, Optional
+
+from .metadata import APIMethodMetadata
+from .registry import API_REGISTRY
+
+
+def api_method(
+    cli_name: Optional[str] = None,
+    description: Optional[str] = None,
+    category: str = "general",
+    requires_vm: bool = False,
+    examples: Optional[List[str]] = None,
+    aliases: Optional[List[str]] = None,
+    hidden: bool = False,
+    parent: Optional[str] = None,
+) -> Callable:
+    """
+    Decorate MAQET API methods to enable unified CLI and Python API generation.
+
+    This decorator captures method metadata that is used by generators to automatically
+    create CLI commands and Python API methods from the same source.
+
+    Args:
+        cli_name: CLI command name (defaults to method name with underscores as dashes)
+        description: Human-readable description (defaults to docstring summary)
+        category: Method category for grouping ('vm', 'qmp', 'storage', 'system')
+        requires_vm: Whether this method requires a VM to be specified
+        examples: List of usage examples
+        aliases: Alternative CLI command names
+        hidden: Whether to hide from CLI help (for internal methods)
+        parent: Parent command name for nested subcommands (e.g., 'qmp')
+
+    Returns:
+        Decorated function with metadata attached
+
+    Example:
+        @api_method(
+            cli_name="start",
+            description="Start a virtual machine",
+            category="vm",
+            requires_vm=True,
+            examples=["maqet start myvm", "maqet start myvm --detach"]
+        )
+        def start(self, vm_id: str, detach: bool = False):
+            '''Start a virtual machine.'''
+            # Implementation here
+    """
+
+    def decorator(func: Callable) -> Callable:
+        # Extract description from docstring if not provided
+        if description is None:
+            doc_description = _extract_description_from_docstring(func.__doc__)
+        else:
+            doc_description = description
+
+        # Get method signature
+        signature = inspect.signature(func)
+
+        # Create metadata
+        metadata = APIMethodMetadata(
+            name=func.__name__,
+            function=func,
+            owner_class="",  # Will be set when method is bound to a class
+            cli_name=cli_name,
+            description=doc_description,
+            signature=signature,
+            category=category,
+            requires_vm=requires_vm,
+            examples=examples or [],
+            aliases=aliases or [],
+            hidden=hidden,
+            parent=parent,
+        )
+
+        # Store metadata on the function for later registration
+        func._api_metadata = metadata
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+
+        # Copy metadata to wrapper
+        wrapper._api_metadata = metadata
+
+        return wrapper
+
+    return decorator
+
+
+def _extract_description_from_docstring(docstring: Optional[str]) -> str:
+    """
+    Extract first line of docstring as description.
+
+    Args:
+        docstring: Function docstring
+
+    Returns:
+        First non-empty line of docstring or default message
+    """
+    if not docstring:
+        return "No description available"
+
+    lines = [line.strip() for line in docstring.strip().split("\n")]
+    first_line = next((line for line in lines if line), "")
+
+    return first_line or "No description available"
+
+
+class AutoRegisterAPI:
+    """
+    Base class that automatically registers @api_method decorated methods.
+
+    Any class that inherits from this will automatically have its @api_method
+    decorated methods registered with the global API registry when the class
+    is defined. This eliminates the need for manual register_class_methods() calls.
+
+    Example:
+        class Maqet(AutoRegisterAPI):
+            @api_method(category="vm")
+            def start(self, vm_id: str):
+                pass
+
+        # Methods are automatically registered - no manual call needed!
+    """
+
+    def __init_subclass__(cls, **kwargs):
+        """
+        Automatically register decorated methods when a subclass is created.
+
+        This method is called whenever a class inherits from AutoRegisterAPI,
+        enabling automatic registration without manual function calls.
+        """
+        super().__init_subclass__(**kwargs)
+
+        # Register all @api_method decorated methods from this class
+        for name, method in inspect.getmembers(
+            cls, predicate=inspect.isfunction
+        ):
+            if hasattr(method, "_api_metadata"):
+                metadata: APIMethodMetadata = method._api_metadata
+                # Set the owner class now that we know it
+                metadata.owner_class = cls.__name__
+                # Register with global registry
+                API_REGISTRY.register(metadata)
+
+
+def register_class_methods(cls: type) -> None:
+    """
+    Register all @api_method decorated methods from a class.
+
+    This function should be called after class definition to register
+    all decorated methods with the global API registry.
+
+    NOTE: This function is kept for backward compatibility, but new code
+    should inherit from AutoRegisterAPI instead for automatic registration.
+
+    Args:
+        cls: Class containing decorated methods
+
+    Example:
+        class Maqet:
+            @api_method(category="vm")
+            def start(self, vm_id: str):
+                pass
+
+        register_class_methods(Maqet)
+
+    """
+    for name, method in inspect.getmembers(cls, predicate=inspect.isfunction):
+        if hasattr(method, "_api_metadata"):
+            metadata: APIMethodMetadata = method._api_metadata
+            # Set the owner class now that we know it
+            metadata.owner_class = cls.__name__
+            # Register with global registry
+            API_REGISTRY.register(metadata)

maqet/api/metadata.py

@@ -0,0 +1,147 @@
+"""
+API Method Metadata.
+
+Data structures for capturing metadata about decorated API methods
+to enable automatic CLI and Python API generation.
+"""
+
+import inspect
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+
+@dataclass
+class APIMethodMetadata:
+    """
+    Metadata captured from @api_method decorated functions.
+
+    This data structure contains all the information needed by generators to create
+    CLI commands and Python API methods from a single decorated method definition.
+
+    Attributes:
+        name: Original method name (e.g., 'start_vm')
+        function: The actual callable function
+        owner_class: Class that owns this method (e.g., 'Maqet')
+        cli_name: CLI command name (e.g., 'start-vm', defaults to name with dashes)
+        description: Human-readable description for help text
+        signature: Function signature for parameter validation
+        category: Grouping category ('vm', 'qmp', 'storage', 'system')
+        requires_vm: Whether this method requires a VM identifier
+        examples: List of usage examples for documentation
+        aliases: Alternative CLI command names
+        hidden: Whether to hide from CLI help (for internal methods)
+        parent: Parent command name for nested subcommands (e.g., 'qmp')
+
+    Example:
+        >>> metadata = APIMethodMetadata(
+        ...     name='start',
+        ...     function=start_method,
+        ...     owner_class='Maqet',
+        ...     cli_name='start',
+        ...     description='Start a virtual machine',
+        ...     signature=inspect.signature(start_method),
+        ...     category='vm',
+        ...     requires_vm=True
+        ... )
+    """
+
+    name: str
+    function: Callable
+    owner_class: str
+    cli_name: Optional[str]
+    description: str
+    signature: inspect.Signature
+    category: str
+    requires_vm: bool = False
+    examples: List[str] = field(default_factory=list)
+    aliases: List[str] = field(default_factory=list)
+    hidden: bool = False
+    parent: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        """
+        Set defaults and validate metadata after initialization.
+
+        Automatically converts method names to CLI-friendly format
+        (underscores become dashes) if cli_name is not explicitly set.
+        """
+        if self.cli_name is None:
+            self.cli_name = self.name.replace("_", "-")
+
+    @property
+    def full_name(self) -> str:
+        """
+        Get fully qualified method name including class.
+
+        Returns:
+            Full method name in format "ClassName.method_name"
+
+        Example:
+            >>> metadata.full_name
+            'Maqet.start'
+        """
+        return f"{self.owner_class}.{self.name}"
+
+    @property
+    def parameters(self) -> Dict[str, inspect.Parameter]:
+        """
+        Get method parameters excluding 'self'.
+
+        Returns:
+            Dictionary of parameter names to inspect.Parameter objects,
+            with 'self' parameter filtered out for instance methods.
+
+        Example:
+            >>> params = metadata.parameters
+            >>> list(params.keys())
+            ['vm_id', 'detach', 'wait']
+        """
+        params = dict(self.signature.parameters)
+        params.pop("self", None)
+        return params
+
+    @property
+    def required_parameters(self) -> List[str]:
+        """
+        Get list of required parameter names.
+
+        Returns:
+            List of parameter names that have no default value
+            and are therefore required when calling the method.
+            Excludes VAR_POSITIONAL (*args) and VAR_KEYWORD (**kwargs)
+            parameters as they are always optional.
+
+        Example:
+            >>> metadata.required_parameters
+            ['vm_id']
+        """
+        required = []
+        for name, param in self.parameters.items():
+            # Skip *args and **kwargs parameters - they're always optional
+            if param.kind in (
+                inspect.Parameter.VAR_POSITIONAL,
+                inspect.Parameter.VAR_KEYWORD,
+            ):
+                continue
+            if param.default == inspect.Parameter.empty:
+                required.append(name)
+        return required
+
+    @property
+    def optional_parameters(self) -> List[str]:
+        """
+        Get list of optional parameter names.
+
+        Returns:
+            List of parameter names that have default values
+            and are therefore optional when calling the method.
+
+        Example:
+            >>> metadata.optional_parameters
+            ['detach', 'wait']
+        """
+        optional = []
+        for name, param in self.parameters.items():
+            if param.default != inspect.Parameter.empty:
+                optional.append(name)
+        return optional