freyja 0.0.0__py3-none-any.whl

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2019] [Tangled Path]
+
+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.

README.md

@@ -0,0 +1,309 @@
+![Freyja](freyja.png)
+
+# Freyja ⚡
+**No-dependency, zero-configuration CLI tool to build command-line interfaces purely from your code.**
+
+Transform your Python functions and classes into powerful command-line applications in seconds! Freyja uses introspection and type annotations to automatically generate professional CLIs with zero configuration required.
+
+## Table of Contents
+* [🚀 Why Freyja?](#-why-freyja)
+* [⚡ Quick Start](#-quick-start)
+* [🗂️ Module-based CLI](#️-module-based-cli)
+* [🏗️ Class-based CLI](#️-class-based-cli)
+  * [Direct Methods Pattern](#direct-methods-pattern)
+  * [Inner Classes Pattern](#inner-classes-pattern)
+* [✨ Key Features](#-key-features)
+* [📚 Documentation](#-documentation)
+* [🛠️ Development](#️-development)
+* [⚙️ Requirements](#️-requirements)
+
+## 🚀 Why Freyja?
+
+**Build CLIs in under 5 minutes!** No configuration files, no complex setup, no learning curve. Just add type annotations to your functions and Freyja does the rest.
+
+```bash
+pip install freyja
+# That's it! No dependencies, no configuration needed.
+```
+
+**Before Freyja:**
+```bash
+python script.py --config-file /path/to/config --database-host localhost --database-port 5432 --username admin --password secret --table-name users --action create --data '{"name": "Alice", "email": "alice@example.com"}'
+```
+
+**After Freyja:**
+```bash
+python script.py database--create-user --name Alice --email alice@example.com
+# Global config handled automatically, clean syntax, built-in help
+```
+
+## ⚡ Quick Start
+
+**Step 1:** Install Freyja
+```bash
+pip install freyja
+```
+
+**Step 2:** Add type annotations to your functions
+```python
+def greet(name: str = "World", excited: bool = False) -> None:
+    """Greet someone by name."""
+    greeting = f"Hello, {name}!"
+    if excited:
+        greeting += " 🎉"
+    print(greeting)
+```
+
+**Step 3:** Add 3 lines of Freyja code
+```python
+from freyja import CLI
+import sys
+
+if __name__ == '__main__':
+    cli = CLI(sys.modules[__name__], title="My CLI")
+    cli.display()
+```
+
+**Step 4:** Use your new CLI!
+```bash
+python script.py greet --name Alice --excited
+# Output: Hello, Alice! 🎉
+
+python script.py --help
+# Automatic help generation with beautiful formatting
+```
+
+## 🗂️ Module-based CLI
+
+Perfect for functional programming styles and simple utilities. Every function becomes a command:
+
+```python
+# data_processor.py
+from freyja import CLI
+import sys
+
+
+def process_csv(input_file: str, output_format: str = "json", verbose: bool = False) -> None:
+    """Process CSV file and convert to specified format."""
+    print(f"Processing {input_file} -> {output_format}")
+    if verbose:
+        print("Verbose mode enabled")
+
+
+def analyze_logs(log_file: str, pattern: str, max_lines: int = 1000) -> None:
+    """Analyze log files for specific patterns."""
+    print(f"Analyzing {log_file} for pattern: {pattern} (max {max_lines} lines)")
+
+
+if __name__ == '__main__':
+    cli = CLI(sys.modules[__name__], title="Data Processing Tools")
+    cli.display()
+```
+
+**Usage:**
+```bash
+python data_processor.py process-csv --input-file data.csv --output-format xml --verbose
+python data_processor.py analyze-logs --log-file app.log --pattern "ERROR" --max-lines 500
+python data_processor.py --help  # Beautiful auto-generated help
+```
+
+## 🏗️ Class-based CLI
+
+Ideal for stateful applications and complex workflows. Supports two powerful patterns:
+
+### Direct Methods Pattern
+
+Simple and clean - each method becomes a command:
+
+```python
+# calculator.py
+from freyja import CLI
+
+
+class Calculator:
+    """Advanced calculator with memory and history."""
+
+    def __init__(self, precision: int = 2, memory_enabled: bool = True):
+        """Initialize calculator with global settings."""
+        self.precision = precision
+        self.memory = 0 if memory_enabled else None
+
+    def add(self, a: float, b: float, store_result: bool = False) -> None:
+        """Add two numbers together."""
+        result = round(a + b, self.precision)
+        print(f"{a} + {b} = {result}")
+        
+        if store_result and self.memory is not None:
+            self.memory = result
+            print(f"Result stored in memory: {result}")
+
+    def multiply(self, a: float, b: float) -> None:
+        """Multiply two numbers."""
+        result = round(a * b, self.precision)
+        print(f"{a} × {b} = {result}")
+
+
+if __name__ == '__main__':
+    cli = CLI(Calculator, title="Advanced Calculator")
+    cli.display()
+```
+
+**Usage:**
+```bash
+python calculator.py --precision 4 add --a 3.14159 --b 2.71828 --store-result
+# Output: 3.14159 + 2.71828 = 5.8599
+#         Result stored in memory: 5.8599
+```
+
+### Inner Classes Pattern
+
+Organize complex applications with flat double-dash commands:
+
+```python
+# project_manager.py
+from freyja import CLI
+from pathlib import Path
+
+
+class ProjectManager:
+    """Complete project management suite with organized command structure."""
+
+    def __init__(self, config_file: str = "config.json", debug: bool = False):
+        """Initialize with global settings."""
+        self.config_file = config_file
+        self.debug = debug
+
+    class Database:
+        """Database operations and management."""
+
+        def __init__(self, connection_string: str = "sqlite:///projects.db", timeout: int = 30):
+            """Initialize database connection."""
+            self.connection_string = connection_string
+            self.timeout = timeout
+
+        def migrate(self, version: str = "latest", dry_run: bool = False) -> None:
+            """Run database migrations."""
+            action = "Would run" if dry_run else "Running"
+            print(f"{action} migration to version: {version}")
+            print(f"Connection: {self.connection_string}")
+
+        def backup(self, output_path: Path, compress: bool = True) -> None:
+            """Create database backup."""
+            compression = "compressed" if compress else "uncompressed"
+            print(f"Creating {compression} backup at: {output_path}")
+
+    class Projects:
+        """Project creation and management operations."""
+
+        def __init__(self, workspace: str = "./projects", auto_save: bool = True):
+            """Initialize project operations."""
+            self.workspace = workspace
+            self.auto_save = auto_save
+
+        def create(self, name: str, template: str = "basic", description: str = "") -> None:
+            """Create a new project from template."""
+            print(f"Creating project '{name}' using '{template}' template")
+            print(f"Workspace: {self.workspace}")
+            print(f"Description: {description}")
+            print(f"Auto-save: {'enabled' if self.auto_save else 'disabled'}")
+
+        def deploy(self, project_name: str, environment: str = "staging", force: bool = False) -> None:
+            """Deploy project to specified environment."""
+            action = "Force deploying" if force else "Deploying"
+            print(f"{action} {project_name} to {environment}")
+
+
+if __name__ == '__main__':
+    cli = CLI(ProjectManager, title="Project Management Suite")
+    cli.display()
+```
+
+**Usage:**
+```bash
+# Global + Sub-global + Command arguments (all flat)
+python project_manager.py --config-file prod.json --debug \
+  database--migrate --connection-string postgres://prod --version 2.1.0 --dry-run
+
+# Create new project with custom workspace
+python project_manager.py projects--create --workspace /prod/projects --auto-save \
+  --name "web-app" --template "react" --description "Production web application"
+
+# Deploy with force flag
+python project_manager.py projects--deploy --project-name web-app --environment production --force
+
+# Beautiful help shows all flat commands organized by group
+python project_manager.py --help
+```
+
+## ✨ Key Features
+
+🚀 **Zero Configuration** - Works out of the box with just type annotations  
+⚡ **Lightning Fast** - No runtime dependencies, minimal overhead  
+🎯 **Type Safe** - Automatic validation from your type hints  
+📚 **Auto Documentation** - Help text generated from your docstrings  
+🎨 **Beautiful Output** - Professional themes and formatting  
+🔧 **Flexible Architecture** - Module-based or class-based patterns  
+📦 **No Dependencies** - Uses only Python standard library  
+🌈 **Shell Completion** - Bash, Zsh, Fish, and PowerShell support  
+✅ **Production Ready** - Battle-tested in enterprise applications  
+
+## 📚 Documentation
+
+**[📖 Complete Documentation Hub](docs/README.md)** - Everything you need to master Freyja
+
+### Quick Links
+* **[🚀 Getting Started](docs/getting-started/README.md)** - Installation and first steps
+* **[👤 User Guide](docs/user-guide/README.md)** - Comprehensive guides for both CLI modes  
+* **[⚙️ Features](docs/features/README.md)** - Type annotations, themes, completion, and more
+* **[📋 Examples & Best Practices](docs/guides/README.md)** - Real-world examples and patterns
+* **[❓ FAQ](docs/faq.md)** - Frequently asked questions
+* **[🔧 API Reference](docs/reference/README.md)** - Complete API documentation
+
+## 🛠️ Development
+
+**[📖 Development Guide](CLAUDE.md)** - Comprehensive guide for contributors
+
+### Quick Setup
+
+```bash
+# Clone and setup
+git clone https://github.com/tangledpath/freyja.git
+cd freyja
+
+# Install Poetry and setup environment  
+curl -sSL https://install.python-poetry.org | python3 -
+./bin/setup-dev.sh
+
+# Run tests and examples
+./bin/test.sh
+poetry run python examples/mod_example.py --help
+poetry run python examples/cls_example.py --help
+```
+
+### Development Commands
+
+```bash
+poetry install              # Install dependencies
+./bin/test.sh              # Run tests with coverage
+./bin/lint.sh              # Run all linters and formatters
+poetry build               # Build package
+./bin/publish.sh           # Publish to PyPI (maintainers)
+```
+
+## ⚙️ Requirements
+
+* **Python 3.13.5+** (recommended) or Python 3.8+
+* **Zero runtime dependencies** - uses only Python standard library
+* **Type annotations required** - for automatic CLI generation
+* **Docstrings recommended** - for automatic help text generation
+
+---
+
+**Ready to transform your Python code into powerful CLIs?**
+
+```bash
+pip install freyja
+# Start building amazing command-line tools in minutes! ⚡
+```
+
+**[📚 Get Started Now →](docs/getting-started/README.md)**

freyja/__init__.py

@@ -0,0 +1,8 @@
+"""
+Freyja: Zero-configuration FreyjaCLI generator from classes/module introspection.
+Uses class/method/function introspection, typehints, and docstrings to build
+a fully functional FreyjaCLI.  Command groups can be made with inner-classes,
+effectively making subclasses.
+"""
+from .freyja_cli import FreyjaCLI
+__all__ = [FreyjaCLI]

freyja/cli/__init__.py

@@ -0,0 +1,11 @@
+from .class_handler import ClassHandler
+from .execution_coordinator import ExecutionCoordinator
+from .enums import TargetMode
+from .system import SystemClassBuilder
+
+__all__ = [
+  ClassHandler,
+  ExecutionCoordinator,
+  SystemClassBuilder,
+  TargetMode,
+]

freyja/cli/class_handler.py

@@ -0,0 +1,189 @@
+import inspect
+from typing import Dict, Type, List, Tuple, Optional, Any
+
+"""Multi-class FreyjaCLI command handling and collision detection.
+
+Provides services for managing cmd_tree from multiple classes in a single FreyjaCLI,
+including collision detection, command ordering, and source tracking.
+"""
+
+
+
+class ClassHandler:
+  """Handles cmd_tree from multiple classes with collision detection and ordering."""
+
+  def __init__(self):
+    """Initialize multi-class handler."""
+    self.command_sources: Dict[str, Type] = {}  # command_name -> source_class
+    self.class_commands: Dict[Type, List[str]] = {}  # source_class -> [command_names]
+    self.collision_tracker: Dict[str, List[Type]] = {}  # command_name -> [source_classes]
+
+  def track_command(self, command_name: str, source_class: Type) -> None:
+    """
+    Track a command and its source class for collision detection.
+
+    :param command_name: FreyjaCLI command name (e.g., 'file-operations--process-single')
+    :param source_class: Source class that defines this command
+    """
+    # Track which class this command comes from
+    if command_name in self.command_sources:
+      # Collision detected - track all sources
+      if command_name not in self.collision_tracker:
+        self.collision_tracker[command_name] = [self.command_sources[command_name]]
+      self.collision_tracker[command_name].append(source_class)
+    else:
+      self.command_sources[command_name] = source_class
+
+    # Track cmd_tree per class for ordering
+    if source_class not in self.class_commands:
+      self.class_commands[source_class] = []
+    self.class_commands[source_class].append(command_name)
+
+  def detect_collisions(self) -> List[Tuple[str, List[Type]]]:
+    """
+    Detect and return command name collisions.
+
+    :return: List of (command_name, [conflicting_classes]) tuples
+    """
+    return [(cmd, classes) for cmd, classes in self.collision_tracker.items()]
+
+  def has_collisions(self) -> bool:
+    """
+    Check if any command name collisions exist.
+
+    :return: True if collisions detected, False otherwise
+    """
+    return len(self.collision_tracker) > 0
+
+  def get_ordered_commands(self, class_order: List[Type]) -> List[str]:
+    """
+    Get cmd_tree ordered by class sequence, then alphabetically within each class.
+
+    :param class_order: Desired order of classes
+    :return: List of command names in proper order
+    """
+    ordered_commands = []
+
+    # Process classes in the specified order
+    for cls in class_order:
+      if cls in self.class_commands:
+        # Sort cmd_tree within this class alphabetically
+        class_commands = sorted(self.class_commands[cls])
+        ordered_commands.extend(class_commands)
+
+    return ordered_commands
+
+  def get_command_source(self, command_name: str) -> Optional[Type]:
+    """
+    Get the source class for a command.
+
+    :param command_name: FreyjaCLI command name
+    :return: Source class or None if not found
+    """
+    return self.command_sources.get(command_name)
+
+  def format_collision_error(self) -> str:
+    """
+    Format collision error message for user display.
+
+    :return: Formatted error message describing all collisions
+    """
+    if not self.has_collisions():
+      return ""
+
+    error_lines = ["Command name collisions detected:"]
+
+    for command_name, conflicting_classes in self.collision_tracker.items():
+      class_names = [cls.__name__ for cls in conflicting_classes]
+      error_lines.append(f"  '{command_name}' conflicts between: {', '.join(class_names)}")
+
+    error_lines.append("")
+    error_lines.append("Solutions:")
+    error_lines.append("1. Rename methods in one of the conflicting classes")
+    error_lines.append("2. Use different inner class names to create unique command paths")
+    error_lines.append("3. Use separate FreyjaCLI instances for conflicting classes")
+
+    return "\n".join(error_lines)
+
+  def validate_classes(self, classes: List[Type]) -> None:
+    """Validate that classes can be used together without collisions.
+
+    :param classes: List of classes to validate
+    :raises ValueError: If command collisions are detected"""
+    # Simulate command discovery to detect collisions
+    temp_handler = ClassHandler()
+
+    for cls in classes:
+      # Simulate the command discovery process
+      self._simulate_class_commands(temp_handler, cls)
+
+    # Check for collisions
+    if temp_handler.has_collisions():
+      raise ValueError(temp_handler.format_collision_error())
+
+  def _simulate_class_commands(self, handler: 'ClassHandler', cls: Type) -> None:
+    """Simulate command discovery for collision detection.
+
+    :param handler: Handler to track cmd_tree in
+    :param cls: Class to simulate cmd_tree for"""
+    from freyja.utils.text_util import TextUtil
+
+    # Check for inner classes (hierarchical cmd_tree)
+    inner_classes = self._discover_inner_classes(cls)
+
+    if inner_classes:
+      # Inner class pattern - track both direct methods and inner class methods
+      # Direct methods
+      for name, obj in inspect.getmembers(cls):
+        if self._is_valid_method(name, obj, cls):
+          cli_name = TextUtil.kebab_case(name)
+          handler.track_command(cli_name, cls)
+
+      # Inner class methods
+      for class_name, inner_class in inner_classes.items():
+        command_name = TextUtil.kebab_case(class_name)
+
+        for method_name, method_obj in inspect.getmembers(inner_class):
+          if (not method_name.startswith('_') and
+              callable(method_obj) and
+              method_name != '__init__' and
+              inspect.isfunction(method_obj)):
+            # Create hierarchical command name
+            cli_name = f"{command_name}--{TextUtil.kebab_case(method_name)}"
+            handler.track_command(cli_name, cls)
+    else:
+      # Direct methods only
+      for name, obj in inspect.getmembers(cls):
+        if self._is_valid_method(name, obj, cls):
+          cli_name = TextUtil.kebab_case(name)
+          handler.track_command(cli_name, cls)
+
+  def _discover_inner_classes(self, cls: Type) -> Dict[str, Type]:
+    """Discover inner classes for a given class.
+
+    :param cls: Class to check for inner classes
+    :return: Dictionary of inner class name -> inner class"""
+    inner_classes = {}
+
+    for name, obj in inspect.getmembers(cls):
+      if (inspect.isclass(obj) and
+          not name.startswith('_') and
+          obj.__qualname__.endswith(f'{cls.__name__}.{name}')):
+        inner_classes[name] = obj
+
+    return inner_classes
+
+  def _is_valid_method(self, name: str, obj: Any, cls: Type) -> bool:
+    """Check if a method should be included as a FreyjaCLI command.
+
+    :param name: Method name
+    :param obj: Method object
+    :param cls: Containing class
+    :return: True if method should be included"""
+    return (
+        not name.startswith('_') and
+        callable(obj) and
+        (inspect.isfunction(obj) or inspect.ismethod(obj)) and
+        hasattr(obj, '__qualname__') and
+        cls.__name__ in obj.__qualname__
+    )

freyja/cli/enums.py

@@ -0,0 +1,7 @@
+import enum
+
+
+class TargetMode(enum.Enum):
+    """Target mode enum for command discovery."""
+    MODULE = 'module'
+    CLASS = 'class'

freyja/cli/execution_coordinator.py

@@ -0,0 +1,125 @@
+"""FreyjaCLI execution coordination service.
+
+Handles argument parsing and command execution coordination.
+Extracted from FreyjaCLI class to reduce its size and improve separation of concerns.
+"""
+from typing import *
+
+from .enums import TargetMode
+
+
+class ExecutionCoordinator:
+  """Coordinates FreyjaCLI argument parsing and command execution."""
+
+  def __init__(self, target_mode: TargetMode, executors: Dict[str, Any]):
+    """Initialize execution coordinator."""
+    self.target_mode = target_mode
+    self.executors = executors
+    self.command_tree = None
+
+  def parse_and_execute(self, parser, args: Optional[List[str]]) -> Any:
+    """Parse arguments and execute command."""
+    result = None
+
+    try:
+      parsed = parser.parse_args(args)
+
+      # Debug: Check what attributes are available
+      # parsed_attrs = [attr for attr in dir(parsed) if not attr.startswith('_')]
+      # print(f"DEBUG: parsed attributes: {parsed_attrs}")
+      # print(f"DEBUG: parsed.__dict__: {parsed.__dict__}")
+
+      if not hasattr(parsed, '_cli_function'):
+        # No command specified, show help
+        result = self._handle_no_command(parser, parsed)
+      else:
+        # Execute command
+        result = self._execute_command(parsed)
+
+    except SystemExit:
+      # Let argparse handle its own exits (help, errors, etc.)
+      raise
+
+    except Exception as e:
+      # Handle execution errors - for argparse-like errors, raise SystemExit
+      if isinstance(e, (ValueError, KeyError)) and 'parsed' not in locals():
+        # Parsing errors should raise SystemExit like argparse does
+        print(f"Error: {e}")
+        raise SystemExit(2)
+      else:
+        # Other execution errors
+        result = self._handle_execution_error(parsed if 'parsed' in locals() else None, e)
+
+    return result
+
+  def _handle_no_command(self, parser, parsed) -> int:
+    """Handle case where no command was specified."""
+    if hasattr(parsed, '_complete') and parsed._complete:
+      return 0  # Completion mode - don't show help
+
+    # Check for --help flag explicitly
+    if hasattr(parsed, 'help') and parsed.help:
+      parser.print_help()
+      return 0
+
+    # Default: show help and return success
+    parser.print_help()
+    return 0
+
+  def _execute_command(self, parsed) -> Any:
+    """Execute the command from parsed arguments."""
+    # Check if we have multiple classes (multiple executors)
+    if len(self.executors) > 1 and 'primary' not in self.executors:
+      return self._execute_multi_class_command(parsed)
+    else:
+      # Single class or module execution
+      executor = self.executors.get('primary')
+      if not executor:
+        raise RuntimeError("No executor available for command execution")
+
+      return executor.execute_command(
+        parsed=parsed,
+        target_mode=self.target_mode
+      )
+
+  def _execute_multi_class_command(self, parsed) -> Any:
+    """Execute command for multiple-class FreyjaCLI."""
+    function_name = parsed._function_name
+    source_class = self._find_source_class_for_function(function_name)
+
+    if not source_class:
+      raise ValueError(f"Could not find source class for function: {function_name}")
+
+    executor = self.executors.get(source_class)
+
+    if not executor:
+      raise ValueError(f"No executor found for class: {source_class.__name__}")
+
+    return executor.execute_command(
+      parsed=parsed,
+      target_mode=TargetMode.CLASS
+    )
+
+  def _find_source_class_for_function(self, function_name: str) -> Optional[Type]:
+    """Find the source class for a given function name."""
+    if self.command_tree:
+      return self.command_tree.find_source_class(function_name)
+    return None
+
+  def _handle_execution_error(self, parsed, error: Exception) -> int:
+    """Handle command execution errors."""
+    if isinstance(error, KeyboardInterrupt):
+      print("\nOperation cancelled by user")
+      return 130  # Standard exit code for SIGINT
+
+    print(f"Error executing command: {error}")
+    
+    if parsed and hasattr(parsed, '_function_name'):
+      print(f"Function: {parsed._function_name}")
+    
+    return 1
+
+  @staticmethod
+  def check_no_color_flag(args: List[str]) -> bool:
+    """Check if --no-color flag is present in arguments."""
+    return '--no-color' in args or '-n' in args

freyja/cli/system/__init__.py

@@ -0,0 +1,16 @@
+from .completion import Completion
+from .tune_theme import TuneTheme
+
+class SystemClassBuilder:
+  @staticmethod
+  def build(completion:bool=True, theme_tuner:bool=False) -> type:
+    system_class_dict:dict = {}
+
+    if completion: system_class_dict['Completion'] = Completion
+    if theme_tuner: system_class_dict['TuneTheme'] =  TuneTheme
+    return type('System', (object,), system_class_dict)
+
+# Create default System class for direct import
+System = SystemClassBuilder.build(completion=True, theme_tuner=True)
+
+__all__ = ['SystemClassBuilder', 'System', 'Completion', 'TuneTheme']