fishertools 0.2.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

fishertools/patterns/logger.py

@@ -0,0 +1,140 @@
+"""
+SimpleLogger pattern for file-based logging.
+
+This module provides the SimpleLogger class for adding logging to applications
+without complex configuration. Messages are written to a file with timestamps
+and log levels.
+
+Example:
+    logger = SimpleLogger("app.log")
+    logger.info("Application started")
+    logger.warning("Low memory detected")
+    logger.error("Connection failed")
+"""
+
+import os
+from datetime import datetime
+from pathlib import Path
+
+
+class SimpleLogger:
+    """
+    Simple file-based logging with timestamps and levels.
+
+    This class provides a straightforward way to log messages to a file with
+    automatic timestamps and log level indicators. No configuration is required.
+
+    Parameters:
+        file_path (str): Path to the log file. Created automatically if it
+                        doesn't exist. Parent directories are created as needed.
+
+    Attributes:
+        file_path (str): The path to the log file.
+
+    Methods:
+        info(message): Log an info-level message.
+        warning(message): Log a warning-level message.
+        error(message): Log an error-level message.
+
+    Raises:
+        IOError: If file operations fail.
+
+    Example:
+        logger = SimpleLogger("logs/app.log")
+        logger.info("User logged in")
+        logger.warning("Deprecated function used")
+        logger.error("Database connection failed")
+
+    Note:
+        - Log format: [TIMESTAMP] [LEVEL] message
+        - Timestamp format: YYYY-MM-DD HH:MM:SS
+        - Messages are appended to the file
+        - File is created automatically on first write
+        - Parent directories are created automatically
+    """
+
+    def __init__(self, file_path):
+        """
+        Initialize SimpleLogger with a file path.
+
+        Parameters:
+            file_path (str): Path to the log file.
+        """
+        self.file_path = file_path
+
+    def info(self, message):
+        """
+        Log an info-level message.
+
+        Parameters:
+            message (str): The message to log.
+
+        Returns:
+            None
+
+        Raises:
+            IOError: If file write fails.
+        """
+        self._log("INFO", message)
+
+    def warning(self, message):
+        """
+        Log a warning-level message.
+
+        Parameters:
+            message (str): The message to log.
+
+        Returns:
+            None
+
+        Raises:
+            IOError: If file write fails.
+        """
+        self._log("WARNING", message)
+
+    def error(self, message):
+        """
+        Log an error-level message.
+
+        Parameters:
+            message (str): The message to log.
+
+        Returns:
+            None
+
+        Raises:
+            IOError: If file write fails.
+        """
+        self._log("ERROR", message)
+
+    def _log(self, level, message):
+        """
+        Internal method to write a log message.
+
+        Parameters:
+            level (str): The log level (INFO, WARNING, ERROR).
+            message (str): The message to log.
+
+        Returns:
+            None
+
+        Raises:
+            IOError: If file write fails.
+        """
+        try:
+            # Create parent directories if they don't exist
+            parent_dir = os.path.dirname(self.file_path)
+            if parent_dir:
+                Path(parent_dir).mkdir(parents=True, exist_ok=True)
+            
+            # Get current timestamp
+            timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+            
+            # Format log message
+            log_entry = f"[{timestamp}] [{level}] {message}\n"
+            
+            # Append to log file with UTF-8 encoding
+            with open(self.file_path, 'a', encoding='utf-8') as f:
+                f.write(log_entry)
+        except IOError as e:
+            raise IOError(f"Failed to write to {self.file_path}: {e}")

fishertools/patterns/menu.py

@@ -0,0 +1,99 @@
+"""
+Simple menu pattern for interactive console menus.
+
+This module provides the simple_menu() function for creating interactive
+console-based menus without complex configuration.
+
+Example:
+    def greet():
+        print("Hello!")
+
+    def goodbye():
+        print("Goodbye!")
+
+    simple_menu({
+        "Greet": greet,
+        "Say goodbye": goodbye
+    })
+"""
+
+
+def simple_menu(options):
+    """
+    Create an interactive console menu.
+
+    Displays a numbered menu of options and prompts the user to select one.
+    The selected option's corresponding function is executed. Invalid selections
+    trigger an error message and re-prompt. The menu exits on "quit" or "exit".
+
+    Parameters:
+        options (dict): Dictionary where keys are display names (str) and
+                       values are callable functions to execute when selected.
+
+    Returns:
+        None
+
+    Raises:
+        TypeError: If options is not a dictionary or values are not callable.
+
+    Example:
+        def save_data():
+            print("Data saved!")
+
+        def load_data():
+            print("Data loaded!")
+
+        simple_menu({
+            "Save": save_data,
+            "Load": load_data
+        })
+
+    Note:
+        - Menu options are displayed with numbers starting from 1
+        - User can type "quit" or "exit" to exit the menu
+        - Invalid selections display an error and re-prompt
+        - Each selected function is called with no arguments
+    """
+    # Validate input
+    if not isinstance(options, dict):
+        raise TypeError("options must be a dictionary")
+    
+    if not options:
+        raise ValueError("options dictionary cannot be empty")
+    
+    # Validate that all values are callable
+    for key, value in options.items():
+        if not callable(value):
+            raise TypeError(f"Value for key '{key}' must be callable")
+    
+    # Convert options to a list to maintain order and allow indexing
+    option_list = list(options.items())
+    
+    while True:
+        # Display menu
+        print("\n" + "=" * 40)
+        for i, (name, _) in enumerate(option_list, 1):
+            print(f"{i}. {name}")
+        print("=" * 40)
+        
+        # Get user input
+        user_input = input("Enter your choice (or 'quit'/'exit' to exit): ").strip().lower()
+        
+        # Check for exit commands
+        if user_input in ("quit", "exit"):
+            print("Exiting menu.")
+            break
+        
+        # Try to parse as a number
+        try:
+            choice = int(user_input)
+            
+            # Check if choice is valid
+            if 1 <= choice <= len(option_list):
+                # Execute the selected function
+                _, func = option_list[choice - 1]
+                func()
+            else:
+                print(f"Error: Please enter a number between 1 and {len(option_list)}.")
+        except ValueError:
+            print("Error: Invalid input. Please enter a number or 'quit'/'exit'.")

fishertools/patterns/storage.py

@@ -0,0 +1,127 @@
+"""
+JSONStorage pattern for persistent data storage.
+
+This module provides the JSONStorage class for saving and loading data
+in JSON format without requiring manual file handling code.
+
+Example:
+    storage = JSONStorage("data.json")
+    storage.save({"name": "Alice", "age": 30})
+    data = storage.load()
+    print(data)  # {"name": "Alice", "age": 30}
+"""
+
+import json
+import os
+from pathlib import Path
+
+
+class JSONStorage:
+    """
+    Persist and retrieve data in JSON format.
+
+    This class handles all file operations for JSON data storage, including
+    automatic directory creation and error handling. Data is stored in a
+    human-readable JSON format.
+
+    Parameters:
+        file_path (str): Path to the JSON file for storage. Parent directories
+                        are created automatically if they don't exist.
+
+    Attributes:
+        file_path (str): The path to the JSON storage file.
+
+    Methods:
+        save(data): Write data to the JSON file.
+        load(): Read data from the JSON file.
+        exists(): Check if the storage file exists.
+
+    Raises:
+        IOError: If file operations fail.
+        json.JSONDecodeError: If the JSON file is corrupted.
+
+    Example:
+        storage = JSONStorage("config/app.json")
+        storage.save({"theme": "dark", "language": "en"})
+        config = storage.load()
+        if storage.exists():
+            print("Config file exists")
+
+    Note:
+        - Parent directories are created automatically
+        - File is created on first save if it doesn't exist
+        - Existing files are overwritten when saving
+        - Load returns an empty dict if file doesn't exist
+    """
+
+    def __init__(self, file_path):
+        """
+        Initialize JSONStorage with a file path.
+
+        Parameters:
+            file_path (str): Path to the JSON storage file.
+        """
+        self.file_path = file_path
+
+    def save(self, data):
+        """
+        Save data to the JSON file.
+
+        Parameters:
+            data (dict): Data to save. Must be JSON-serializable.
+
+        Returns:
+            None
+
+        Raises:
+            IOError: If file write fails.
+            TypeError: If data is not JSON-serializable.
+        """
+        try:
+            # Create parent directories if they don't exist
+            parent_dir = os.path.dirname(self.file_path)
+            if parent_dir:
+                Path(parent_dir).mkdir(parents=True, exist_ok=True)
+            
+            # Write data to JSON file
+            with open(self.file_path, 'w') as f:
+                json.dump(data, f, indent=2)
+        except TypeError as e:
+            raise TypeError(f"Data is not JSON-serializable: {e}")
+        except IOError as e:
+            raise IOError(f"Failed to write to {self.file_path}: {e}")
+
+    def load(self):
+        """
+        Load data from the JSON file.
+
+        Returns:
+            dict: The loaded data, or empty dict if file doesn't exist.
+
+        Raises:
+            IOError: If file read fails.
+            json.JSONDecodeError: If the JSON file is corrupted.
+        """
+        try:
+            if not os.path.exists(self.file_path):
+                return {}
+            
+            with open(self.file_path, 'r') as f:
+                return json.load(f)
+        except json.JSONDecodeError as e:
+            raise json.JSONDecodeError(
+                f"Failed to parse JSON from {self.file_path}: {e.msg}",
+                e.doc,
+                e.pos
+            )
+        except IOError as e:
+            raise IOError(f"Failed to read from {self.file_path}: {e}")
+
+    def exists(self):
+        """
+        Check if the storage file exists.
+
+        Returns:
+            bool: True if the file exists, False otherwise.
+        """
+        return os.path.exists(self.file_path)