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

fishertools/examples/cli_example.py

@@ -0,0 +1,156 @@
+"""
+Example demonstrating the SimpleCLI class from fishertools.patterns.
+
+This example shows how to create a command-line interface using SimpleCLI.
+Commands are registered via decorators and executed based on command-line
+arguments. Supports --help flag and graceful error handling.
+
+Run this file with various commands to see SimpleCLI in action:
+  python cli_example.py greet Alice
+  python cli_example.py add 5 3
+  python cli_example.py --help
+"""
+
+from fishertools.patterns import SimpleCLI
+
+
+def main():
+    """Create and run a CLI application."""
+    
+    # Create a CLI instance
+    cli = SimpleCLI("calculator", "A simple calculator application")
+    
+    # Register commands using decorators
+    
+    @cli.command("greet", "Greet someone with a message")
+    def greet(name="World"):
+        """Greet a person by name."""
+        print(f"Hello, {name}! Welcome to the calculator app.")
+    
+    @cli.command("add", "Add two numbers")
+    def add(a, b):
+        """Add two numbers and display the result."""
+        try:
+            result = float(a) + float(b)
+            print(f"{a} + {b} = {result}")
+        except ValueError:
+            print(f"Error: '{a}' and '{b}' must be valid numbers")
+    
+    @cli.command("subtract", "Subtract two numbers")
+    def subtract(a, b):
+        """Subtract b from a and display the result."""
+        try:
+            result = float(a) - float(b)
+            print(f"{a} - {b} = {result}")
+        except ValueError:
+            print(f"Error: '{a}' and '{b}' must be valid numbers")
+    
+    @cli.command("multiply", "Multiply two numbers")
+    def multiply(a, b):
+        """Multiply two numbers and display the result."""
+        try:
+            result = float(a) * float(b)
+            print(f"{a} * {b} = {result}")
+        except ValueError:
+            print(f"Error: '{a}' and '{b}' must be valid numbers")
+    
+    @cli.command("divide", "Divide two numbers")
+    def divide(a, b):
+        """Divide a by b and display the result."""
+        try:
+            a_float = float(a)
+            b_float = float(b)
+            if b_float == 0:
+                print("Error: Cannot divide by zero")
+            else:
+                result = a_float / b_float
+                print(f"{a} / {b} = {result}")
+        except ValueError:
+            print(f"Error: '{a}' and '{b}' must be valid numbers")
+    
+    @cli.command("power", "Raise a number to a power")
+    def power(base, exponent):
+        """Raise base to the power of exponent."""
+        try:
+            result = float(base) ** float(exponent)
+            print(f"{base} ^ {exponent} = {result}")
+        except ValueError:
+            print(f"Error: '{base}' and '{exponent}' must be valid numbers")
+    
+    @cli.command("square", "Calculate the square of a number")
+    def square(number):
+        """Calculate the square of a number."""
+        try:
+            result = float(number) ** 2
+            print(f"{number}² = {result}")
+        except ValueError:
+            print(f"Error: '{number}' must be a valid number")
+    
+    @cli.command("sqrt", "Calculate the square root of a number")
+    def sqrt(number):
+        """Calculate the square root of a number."""
+        try:
+            num = float(number)
+            if num < 0:
+                print("Error: Cannot calculate square root of negative number")
+            else:
+                result = num ** 0.5
+                print(f"√{number} = {result}")
+        except ValueError:
+            print(f"Error: '{number}' must be a valid number")
+    
+    @cli.command("info", "Show information about this application")
+    def show_info():
+        """Display information about the calculator."""
+        print("\n" + "=" * 60)
+        print("Calculator Application - SimpleCLI Demo")
+        print("=" * 60)
+        print("\nThis is a demonstration of the SimpleCLI pattern from")
+        print("fishertools.patterns module.")
+        print("\nFeatures:")
+        print("  • Command registration via decorators")
+        print("  • Automatic help generation")
+        print("  • Graceful error handling")
+        print("  • Support for multiple arguments")
+        print("\nUsage examples:")
+        print("  python cli_example.py greet Alice")
+        print("  python cli_example.py add 10 5")
+        print("  python cli_example.py multiply 3.5 2")
+        print("  python cli_example.py divide 20 4")
+        print("  python cli_example.py power 2 8")
+        print("  python cli_example.py square 7")
+        print("  python cli_example.py sqrt 16")
+        print("  python cli_example.py --help")
+        print("=" * 60 + "\n")
+    
+    @cli.command("demo", "Run a demonstration of all commands")
+    def run_demo():
+        """Run a demonstration of all calculator functions."""
+        print("\n" + "=" * 60)
+        print("Calculator Demo - Running all operations")
+        print("=" * 60 + "\n")
+        
+        print("1. Greeting:")
+        greet("Demo User")
+        
+        print("\n2. Basic arithmetic:")
+        add("10", "5")
+        subtract("10", "5")
+        multiply("10", "5")
+        divide("10", "5")
+        
+        print("\n3. Power operations:")
+        power("2", "8")
+        square("7")
+        sqrt("16")
+        
+        print("\n" + "=" * 60)
+        print("Demo complete!")
+        print("=" * 60 + "\n")
+    
+    # Run the CLI
+    cli.run()
+
+
+if __name__ == "__main__":
+    main()

fishertools/examples/learn_example.py

@@ -0,0 +1,65 @@
+"""
+Example demonstrating the explain() function from fishertools.learn.
+
+This example shows how to use the explain() function to get structured
+explanations for Python topics, including descriptions, usage guidance,
+and code examples.
+
+Run this file to see explanations for various Python topics.
+"""
+
+from fishertools.learn import explain
+
+
+def main():
+    """Demonstrate the explain() function with various topics."""
+    
+    print("=" * 70)
+    print("fishertools Learning Tools - explain() Function Demo")
+    print("=" * 70)
+    
+    # List of topics to demonstrate
+    topics = ["list", "for", "lambda", "try", "with"]
+    
+    for topic in topics:
+        try:
+            print(f"\n{'─' * 70}")
+            print(f"Topic: {topic.upper()}")
+            print(f"{'─' * 70}")
+            
+            # Get the explanation
+            explanation = explain(topic)
+            
+            # Display the explanation
+            print(f"\n📖 Description:")
+            print(f"   {explanation['description']}")
+            
+            print(f"\n💡 When to use:")
+            print(f"   {explanation['when_to_use']}")
+            
+            print(f"\n💻 Example:")
+            print("   " + "\n   ".join(explanation['example'].split("\n")))
+            
+        except ValueError as e:
+            print(f"❌ Error: {e}")
+        except Exception as e:
+            print(f"❌ Unexpected error: {e}")
+    
+    # Demonstrate error handling with invalid topic
+    print(f"\n{'─' * 70}")
+    print("Demonstrating error handling with invalid topic:")
+    print(f"{'─' * 70}")
+    
+    try:
+        explain("invalid_topic_xyz")
+    except ValueError as e:
+        print(f"✓ Caught expected error:")
+        print(f"  {e}")
+    
+    print("\n" + "=" * 70)
+    print("Demo complete!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

fishertools/examples/logger_example.py

@@ -0,0 +1,176 @@
+"""
+Example demonstrating the SimpleLogger class from fishertools.patterns.
+
+This example shows how to use SimpleLogger to add logging to applications
+without complex configuration. Demonstrates info, warning, and error logging
+with automatic timestamps and log levels.
+
+Run this file to see SimpleLogger in action.
+"""
+
+import os
+import time
+from fishertools.patterns import SimpleLogger
+
+
+def main():
+    """Demonstrate SimpleLogger functionality."""
+    
+    print("=" * 70)
+    print("fishertools Patterns - SimpleLogger Demo")
+    print("=" * 70)
+    
+    # Create a logger instance
+    log_file = "demo_app.log"
+    logger = SimpleLogger(log_file)
+    
+    # Clean up any existing log file from previous runs
+    if os.path.exists(log_file):
+        os.remove(log_file)
+        print(f"\n✓ Cleaned up existing {log_file}")
+    
+    # Example 1: Basic logging
+    print("\n" + "─" * 70)
+    print("Example 1: Basic logging with different levels")
+    print("─" * 70)
+    
+    print("\nLogging messages...")
+    logger.info("Application started")
+    logger.info("Configuration loaded successfully")
+    logger.warning("Deprecated API endpoint used")
+    logger.error("Failed to connect to database")
+    
+    print("✓ Messages logged to", log_file)
+    
+    # Example 2: Simulating application workflow
+    print("\n" + "─" * 70)
+    print("Example 2: Simulating application workflow")
+    print("─" * 70)
+    
+    print("\nSimulating user registration workflow...")
+    
+    logger.info("User registration started")
+    logger.info("Validating email: user@example.com")
+    
+    time.sleep(0.5)  # Simulate processing
+    
+    logger.info("Email validation passed")
+    logger.info("Checking username availability")
+    
+    time.sleep(0.5)  # Simulate processing
+    
+    logger.info("Username 'john_doe' is available")
+    logger.info("Creating user account")
+    
+    time.sleep(0.5)  # Simulate processing
+    
+    logger.info("User account created successfully")
+    logger.info("Sending welcome email")
+    logger.info("User registration completed")
+    
+    print("✓ Workflow logged successfully")
+    
+    # Example 3: Error handling and warnings
+    print("\n" + "─" * 70)
+    print("Example 3: Error handling and warnings")
+    print("─" * 70)
+    
+    print("\nSimulating error scenarios...")
+    
+    logger.warning("Memory usage above 80%")
+    logger.warning("Cache hit rate below threshold")
+    logger.error("Connection timeout after 30 seconds")
+    logger.error("Failed to save user preferences")
+    logger.info("Attempting automatic recovery")
+    logger.info("Recovery successful")
+    
+    print("✓ Error scenarios logged")
+    
+    # Example 4: Nested directory logging
+    print("\n" + "─" * 70)
+    print("Example 4: Logging to nested directories")
+    print("─" * 70)
+    
+    nested_log_file = "logs/2024/01/application.log"
+    nested_logger = SimpleLogger(nested_log_file)
+    
+    print(f"\nCreating logger for nested path: {nested_log_file}")
+    nested_logger.info("Nested logging initialized")
+    nested_logger.info("This log is in a nested directory structure")
+    
+    print(f"✓ Nested directories created automatically")
+    print(f"✓ Logging to {nested_log_file}")
+    
+    # Example 5: Display the log file contents
+    print("\n" + "─" * 70)
+    print("Example 5: Reading log file contents")
+    print("─" * 70)
+    
+    print(f"\nContents of {log_file}:")
+    print("─" * 70)
+    
+    try:
+        with open(log_file, 'r', encoding='utf-8') as f:
+            log_contents = f.read()
+            print(log_contents)
+    except FileNotFoundError:
+        print(f"✗ Log file {log_file} not found")
+    
+    print("─" * 70)
+    
+    # Example 6: Demonstrating log levels
+    print("\n" + "─" * 70)
+    print("Example 6: Different log levels")
+    print("─" * 70)
+    
+    info_logger = SimpleLogger("info_demo.log")
+    
+    print("\nLogging different severity levels...")
+    info_logger.info("This is an informational message")
+    info_logger.warning("This is a warning message")
+    info_logger.error("This is an error message")
+    
+    print("✓ Different log levels demonstrated")
+    
+    # Display the info demo log
+    print(f"\nContents of info_demo.log:")
+    print("─" * 70)
+    
+    try:
+        with open("info_demo.log", 'r', encoding='utf-8') as f:
+            print(f.read())
+    except FileNotFoundError:
+        print("✗ Log file not found")
+    
+    print("─" * 70)
+    
+    # Cleanup
+    print("\n" + "─" * 70)
+    print("Cleanup")
+    print("─" * 70)
+    
+    files_to_remove = [log_file, "info_demo.log", nested_log_file]
+    
+    for file_to_remove in files_to_remove:
+        if os.path.exists(file_to_remove):
+            os.remove(file_to_remove)
+            print(f"✓ Removed {file_to_remove}")
+    
+    # Remove empty directories
+    dirs_to_remove = ["logs/2024/01", "logs/2024", "logs"]
+    
+    for dir_to_remove in dirs_to_remove:
+        if os.path.exists(dir_to_remove):
+            try:
+                os.rmdir(dir_to_remove)
+                print(f"✓ Removed directory {dir_to_remove}")
+            except OSError:
+                pass
+    
+    print("\n" + "=" * 70)
+    print("SimpleLogger demo complete!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

fishertools/examples/menu_example.py

@@ -0,0 +1,101 @@
+"""
+Example demonstrating the simple_menu() function from fishertools.patterns.
+
+This example shows how to create an interactive console menu using the
+simple_menu() function. The menu allows users to select options and execute
+corresponding functions.
+
+Run this file to interact with the menu.
+"""
+
+from fishertools.patterns import simple_menu
+
+
+def show_greeting():
+    """Display a greeting message."""
+    name = input("What's your name? ")
+    print(f"Hello, {name}! Welcome to the menu demo.")
+
+
+def show_calculator():
+    """Simple calculator menu."""
+    print("\n--- Simple Calculator ---")
+    try:
+        a = float(input("Enter first number: "))
+        b = float(input("Enter second number: "))
+        
+        print(f"\nResults:")
+        print(f"  {a} + {b} = {a + b}")
+        print(f"  {a} - {b} = {a - b}")
+        print(f"  {a} * {b} = {a * b}")
+        if b != 0:
+            print(f"  {a} / {b} = {a / b}")
+        else:
+            print(f"  {a} / {b} = Cannot divide by zero")
+    except ValueError:
+        print("❌ Invalid input. Please enter numbers.")
+
+
+def show_about():
+    """Display information about the demo."""
+    print("\n--- About This Demo ---")
+    print("This is a demonstration of the simple_menu() function")
+    print("from fishertools.patterns module.")
+    print("\nFeatures:")
+    print("  • Interactive menu with numbered options")
+    print("  • Easy function execution")
+    print("  • Graceful error handling")
+    print("  • Exit with 'quit' or 'exit' command")
+
+
+def list_fruits():
+    """Display a list of fruits."""
+    fruits = ["Apple", "Banana", "Cherry", "Date", "Elderberry"]
+    print("\n--- Available Fruits ---")
+    for i, fruit in enumerate(fruits, 1):
+        print(f"  {i}. {fruit}")
+
+
+def show_help():
+    """Display help information."""
+    print("\n--- Help ---")
+    print("This menu demonstrates the simple_menu() function.")
+    print("\nHow to use:")
+    print("  1. Select an option by entering its number")
+    print("  2. Follow the prompts for each option")
+    print("  3. Type 'quit' or 'exit' to leave the menu")
+    print("\nAvailable options:")
+    print("  • Greeting: Get a personalized greeting")
+    print("  • Calculator: Perform basic math operations")
+    print("  • Fruits: See a list of fruits")
+    print("  • About: Learn about this demo")
+    print("  • Help: Show this help message")
+
+
+def main():
+    """Run the menu demo."""
+    print("=" * 60)
+    print("fishertools Patterns - simple_menu() Demo")
+    print("=" * 60)
+    print("\nWelcome! This demo shows how to use simple_menu().")
+    print("Type 'quit' or 'exit' at any time to leave.\n")
+    
+    # Create the menu with options
+    menu_options = {
+        "Greeting": show_greeting,
+        "Calculator": show_calculator,
+        "Fruits": list_fruits,
+        "About": show_about,
+        "Help": show_help,
+    }
+    
+    # Run the menu
+    simple_menu(menu_options)
+    
+    print("\n" + "=" * 60)
+    print("Thank you for using the menu demo!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

fishertools/examples/storage_example.py

@@ -0,0 +1,175 @@
+"""
+Example demonstrating the JSONStorage class from fishertools.patterns.
+
+This example shows how to use JSONStorage to persist and retrieve data
+in JSON format without writing file handling code. Demonstrates saving,
+loading, and checking file existence.
+
+Run this file to see JSONStorage in action.
+"""
+
+import os
+from fishertools.patterns import JSONStorage
+
+
+def main():
+    """Demonstrate JSONStorage functionality."""
+    
+    print("=" * 70)
+    print("fishertools Patterns - JSONStorage Demo")
+    print("=" * 70)
+    
+    # Create a storage instance
+    storage_path = "demo_data.json"
+    storage = JSONStorage(storage_path)
+    
+    # Clean up any existing file from previous runs
+    if os.path.exists(storage_path):
+        os.remove(storage_path)
+        print(f"\n✓ Cleaned up existing {storage_path}")
+    
+    # Example 1: Save data
+    print("\n" + "─" * 70)
+    print("Example 1: Saving data")
+    print("─" * 70)
+    
+    user_data = {
+        "name": "Alice Johnson",
+        "age": 28,
+        "email": "alice@example.com",
+        "skills": ["Python", "JavaScript", "SQL"],
+        "is_active": True,
+        "metadata": {
+            "created": "2024-01-15",
+            "last_login": "2024-01-26"
+        }
+    }
+    
+    print(f"\nSaving user data to {storage_path}:")
+    print(f"  {user_data}")
+    
+    storage.save(user_data)
+    print("✓ Data saved successfully!")
+    
+    # Example 2: Check if file exists
+    print("\n" + "─" * 70)
+    print("Example 2: Checking file existence")
+    print("─" * 70)
+    
+    if storage.exists():
+        print(f"✓ File {storage_path} exists")
+    else:
+        print(f"✗ File {storage_path} does not exist")
+    
+    # Example 3: Load data
+    print("\n" + "─" * 70)
+    print("Example 3: Loading data")
+    print("─" * 70)
+    
+    loaded_data = storage.load()
+    print(f"\nLoaded data from {storage_path}:")
+    print(f"  Name: {loaded_data['name']}")
+    print(f"  Age: {loaded_data['age']}")
+    print(f"  Email: {loaded_data['email']}")
+    print(f"  Skills: {', '.join(loaded_data['skills'])}")
+    print(f"  Active: {loaded_data['is_active']}")
+    print(f"  Created: {loaded_data['metadata']['created']}")
+    
+    # Example 4: Update data
+    print("\n" + "─" * 70)
+    print("Example 4: Updating data")
+    print("─" * 70)
+    
+    loaded_data['age'] = 29
+    loaded_data['skills'].append("Docker")
+    loaded_data['metadata']['last_login'] = "2024-01-26"
+    
+    print(f"\nUpdating user data:")
+    print(f"  Age: 28 → {loaded_data['age']}")
+    print(f"  Skills: Added 'Docker'")
+    print(f"  Last login: Updated to 2024-01-26")
+    
+    storage.save(loaded_data)
+    print("✓ Updated data saved!")
+    
+    # Example 5: Working with nested directories
+    print("\n" + "─" * 70)
+    print("Example 5: Creating nested directories")
+    print("─" * 70)
+    
+    nested_storage_path = "data/users/profiles/alice.json"
+    nested_storage = JSONStorage(nested_storage_path)
+    
+    profile_data = {
+        "username": "alice_dev",
+        "bio": "Python developer and open source enthusiast",
+        "followers": 150,
+        "following": 75
+    }
+    
+    print(f"\nSaving profile to nested path: {nested_storage_path}")
+    nested_storage.save(profile_data)
+    print("✓ Nested directories created automatically!")
+    print(f"✓ Profile saved to {nested_storage_path}")
+    
+    # Verify the nested file was created
+    if nested_storage.exists():
+        print(f"✓ Verified: {nested_storage_path} exists")
+    
+    # Example 6: Round-trip verification
+    print("\n" + "─" * 70)
+    print("Example 6: Round-trip verification")
+    print("─" * 70)
+    
+    original_data = {
+        "items": [1, 2, 3, 4, 5],
+        "config": {
+            "debug": True,
+            "timeout": 30,
+            "retries": 3
+        },
+        "tags": ["important", "urgent", "review"]
+    }
+    
+    roundtrip_storage = JSONStorage("roundtrip_test.json")
+    
+    print(f"\nOriginal data:")
+    print(f"  {original_data}")
+    
+    roundtrip_storage.save(original_data)
+    loaded_roundtrip = roundtrip_storage.load()
+    
+    print(f"\nLoaded data:")
+    print(f"  {loaded_roundtrip}")
+    
+    if original_data == loaded_roundtrip:
+        print("✓ Round-trip successful: Data matches perfectly!")
+    else:
+        print("✗ Round-trip failed: Data mismatch")
+    
+    # Cleanup
+    print("\n" + "─" * 70)
+    print("Cleanup")
+    print("─" * 70)
+    
+    for file_to_remove in [storage_path, nested_storage_path, "roundtrip_test.json"]:
+        if os.path.exists(file_to_remove):
+            os.remove(file_to_remove)
+            print(f"✓ Removed {file_to_remove}")
+    
+    # Remove empty directories
+    for dir_to_remove in ["data/users/profiles", "data/users", "data"]:
+        if os.path.exists(dir_to_remove):
+            try:
+                os.rmdir(dir_to_remove)
+                print(f"✓ Removed directory {dir_to_remove}")
+            except OSError:
+                pass
+    
+    print("\n" + "=" * 70)
+    print("JSONStorage demo complete!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()