8.4 KiB
8.4 KiB
Code Structure
This document provides a detailed overview of Edison's code organization and file structure.
Directory Structure
edison/
├── __init__.py # Package initialization
├── __main__.py # Entry point for module execution
├── cli.py # Command-line interface
├── edison.prompt # Prompt template for command generation
├── edison.yaml # Default configuration file
├── config/ # Configuration management
│ ├── __init__.py
│ └── config_manager.py
├── core/ # Core business logic
│ ├── __init__.py
│ ├── api_client.py # OpenAI API integration
│ ├── command_executor.py # Command execution
│ └── prompt_manager.py # Prompt handling
├── logs/ # Log files directory
├── ui/ # User interface components
│ ├── __init__.py
│ ├── console.py # Console output formatting
│ └── interactive.py # Interactive shell mode
└── utils/ # Utility functions
├── __init__.py
├── logging_utils.py # Logging configuration
├── os_utils.py # OS-specific utilities
└── validation.py # Command validation
Key Files and Their Functions
classDiagram
cli <|-- config_manager
cli <|-- api_client
cli <|-- console
cli <|-- interactive
api_client <|-- prompt_manager
interactive <|-- api_client
interactive <|-- command_executor
class cli {
+main()
+parse_arguments()
}
class config_manager {
+load_config()
+print_config()
}
class api_client {
+create_client()
+generate_command()
+call_api()
+get_api_key()
}
class prompt_manager {
+get_full_prompt()
+load_prompt_template()
}
class command_executor {
+execute_command()
}
class console {
+print_command()
+prompt_user_input()
+handle_command_execution()
+handle_user_input()
}
class interactive {
+interactive_mode()
+get_command_explanation()
+show_help()
}
class logging_utils {
+setup_logging()
+get_logger()
}
class os_utils {
+get_default_shell()
+missing_posix_display()
}
class validation {
+check_for_issue()
+check_for_markdown()
+is_dangerous_command()
}
Core Modules
cli.py
The main entry point and command-line interface for Edison:
- Parses command-line arguments
- Initializes logging
- Loads configuration
- Handles user interaction flow
- Manages error handling
def main():
"""Main entry point for the application."""
# Parse arguments, set up logging, load config, etc.
def parse_arguments():
"""Parse command line arguments."""
# Define and parse command-line arguments
config/config_manager.py
Handles configuration loading and management:
- Loads settings from edison.yaml
- Provides default values
- Validates configuration
def load_config():
"""Load configuration from the YAML file."""
# Find and load the configuration file
def print_config(config):
"""Print the current configuration."""
# Display configuration settings
core/api_client.py
Manages interaction with the OpenAI API:
- Creates and initializes the API client
- Handles API key management
- Formats queries and processes responses
- Implements retry logic
- Supports both streaming and non-streaming command generation
def create_client(config):
"""Create and initialize an OpenAI client."""
# Initialize API client with key
def generate_command(client, config, query, max_retries=3):
"""Generate a command using the OpenAI API with retry logic."""
# Send query to API and handle response
def generate_command_streaming(client, config, query, callback):
"""Generate a command using the OpenAI API with streaming output.
Args:
client: The OpenAI client
config: The configuration dictionary
query: The user query
callback: Function to call with each token
"""
# Stream response tokens and call the callback for each one
core/command_executor.py
Executes shell commands:
- Runs commands in the appropriate shell
- Handles command output and errors
- Implements safety checks
def execute_command(shell, command):
"""Execute a shell command."""
# Run command and handle result
core/prompt_manager.py
Manages prompt templates and formatting:
- Loads prompt templates
- Formats user queries for optimal results
- Adapts prompts based on shell and OS
def get_full_prompt(query, shell="bash"):
"""Get the full prompt for the given query and shell."""
# Format prompt with query and shell info
UI Modules
ui/console.py
Handles console output and user interaction:
- Formats and displays text
- Presents command options
- Handles user input
- Supports direct command modification
- Controls display of generating prefix
def print_command(command, show_generating_prefix=True):
"""Print a command to the console."""
# Display command with formatting, optionally showing the generating prefix
def handle_command_execution(client, config, command, explain=False):
"""Handle the execution of a command."""
# Manage command execution flow
def handle_direct_modification(command):
"""Handle direct modification of a command.
Args:
command: The command to modify
Returns:
The modified command
"""
# Present interactive editor for direct command modification
ui/interactive.py
Provides an interactive shell mode:
- Manages continuous interaction
- Handles command history
- Processes special commands
def interactive_mode(client, config):
"""Start an interactive shell."""
# Run interactive loop
def get_command_explanation(client, command):
"""Get an explanation for a command."""
# Generate explanation
Utility Modules
utils/logging_utils.py
Configures and manages logging:
- Sets up log files and formats
- Controls log levels
- Provides access to loggers
def setup_logging(verbose=False):
"""Configure logging for the application."""
# Set up logging with appropriate levels
utils/os_utils.py
Provides OS-specific functionality:
- Detects platform information
- Manages environment-specific behavior
- Determines default shell
def get_default_shell():
"""Get the default shell for the current OS."""
# Determine system shell
utils/validation.py
Validates and checks commands:
- Detects potentially dangerous commands
- Checks for markdown formatting
- Identifies command issues
def is_dangerous_command(command):
"""Check if a command is potentially dangerous."""
# Analyze command for dangerous patterns
Static Files
- edison.prompt: Template for generating prompts sent to the OpenAI API
- edison.yaml: Default configuration file with settings
Dependencies and Imports
The project uses these key dependencies:
-
Core Python Libraries:
argparse: For command-line argument parsinglogging: For log managementsubprocess: For command executionos,sys: For system interaction
-
External Libraries:
openai: For API interactiontermcolor: For colored terminal outputpython-dotenv: For environment variable loadingpyyaml: For configuration parsingpyperclip: For clipboard operationsprompt_toolkit: For interactive shell functionalitycolorama: For cross-platform color support
Code Style and Conventions
Edison follows these coding conventions:
- PEP 8: Standard Python style guide
- Docstrings: All functions and classes have docstrings in the Google style
- Error Handling: Comprehensive try/except blocks with detailed logging
- Modularity: Functions and classes have single responsibilities
- Type Hints: Not currently used but planned for future versions
Special Considerations
- Cross-Platform Support: Code includes handling for different operating systems
- API Key Security: Multiple secure methods for handling API keys
- Command Safety: Validation to prevent dangerous command execution