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

fishertools/learn/test_knowledge_engine.py

@@ -0,0 +1,241 @@
+"""
+Unit tests for the Knowledge Engine module.
+"""
+
+import pytest
+import os
+import json
+from fishertools.learn.knowledge_engine import (
+    KnowledgeEngine, get_topic, list_topics, search_topics,
+    get_random_topic, get_learning_path, get_engine
+)
+
+
+class TestKnowledgeEngine:
+    """Test suite for KnowledgeEngine class."""
+    
+    @pytest.fixture
+    def engine(self):
+        """Create a KnowledgeEngine instance for testing."""
+        return KnowledgeEngine()
+    
+    def test_engine_initialization(self, engine):
+        """Test that engine initializes correctly."""
+        assert engine is not None
+        assert len(engine.topics) > 0
+        assert len(engine.categories) > 0
+    
+    def test_get_topic_existing(self, engine):
+        """Test getting an existing topic."""
+        topic = engine.get_topic("Lists")
+        assert topic is not None
+        assert topic["topic"] == "Lists"
+        assert "description" in topic
+        assert "example" in topic
+        assert "common_mistakes" in topic
+        assert "related_topics" in topic
+    
+    def test_get_topic_nonexistent(self, engine):
+        """Test getting a non-existent topic returns None."""
+        topic = engine.get_topic("NonExistentTopic")
+        assert topic is None
+    
+    def test_list_topics(self, engine):
+        """Test listing all topics."""
+        topics = engine.list_topics()
+        assert isinstance(topics, list)
+        assert len(topics) == 35
+        assert "Lists" in topics
+        assert "Variables and Assignment" in topics
+        # Check that list is sorted
+        assert topics == sorted(topics)
+    
+    def test_search_topics_by_name(self, engine):
+        """Test searching topics by name."""
+        results = engine.search_topics("list")
+        assert len(results) > 0
+        assert "Lists" in results
+        assert "List Indexing" in results
+        assert "List Slicing" in results
+    
+    def test_search_topics_case_insensitive(self, engine):
+        """Test that search is case-insensitive."""
+        results1 = engine.search_topics("loop")
+        results2 = engine.search_topics("LOOP")
+        assert results1 == results2
+    
+    def test_search_topics_by_description(self, engine):
+        """Test searching topics by description."""
+        results = engine.search_topics("immutable")
+        assert len(results) > 0
+    
+    def test_get_random_topic(self, engine):
+        """Test getting a random topic."""
+        topic = engine.get_random_topic()
+        assert topic is not None
+        assert "topic" in topic
+        assert "description" in topic
+    
+    def test_get_related_topics(self, engine):
+        """Test getting related topics."""
+        related = engine.get_related_topics("Lists")
+        assert isinstance(related, list)
+        # All related topics should exist
+        for topic_name in related:
+            assert engine.get_topic(topic_name) is not None
+    
+    def test_get_related_topics_nonexistent(self, engine):
+        """Test getting related topics for non-existent topic."""
+        related = engine.get_related_topics("NonExistent")
+        assert related == []
+    
+    def test_get_topics_by_category(self, engine):
+        """Test getting topics by category."""
+        basic_types = engine.get_topics_by_category("Basic Types")
+        assert len(basic_types) == 5
+        assert "Variables and Assignment" in basic_types
+        assert "Integers and Floats" in basic_types
+    
+    def test_get_topics_by_category_collections(self, engine):
+        """Test getting Collections category topics."""
+        collections = engine.get_topics_by_category("Collections")
+        assert len(collections) == 6
+    
+    def test_get_topics_by_category_nonexistent(self, engine):
+        """Test getting non-existent category."""
+        topics = engine.get_topics_by_category("NonExistent")
+        assert topics == []
+    
+    def test_get_learning_path(self, engine):
+        """Test getting learning path."""
+        path = engine.get_learning_path()
+        assert isinstance(path, list)
+        assert len(path) == 35
+        # Check that it's ordered by order field
+        assert path[0] == "Variables and Assignment"  # order=1
+        assert path[-1] == "Enumerate"  # order=35
+    
+    def test_topic_structure(self, engine):
+        """Test that all topics have required fields."""
+        for topic_name in engine.list_topics():
+            topic = engine.get_topic(topic_name)
+            assert "topic" in topic
+            assert "category" in topic
+            assert "description" in topic
+            assert "when_to_use" in topic
+            assert "example" in topic
+            assert "common_mistakes" in topic
+            assert "related_topics" in topic
+            assert "difficulty" in topic
+            assert "order" in topic
+    
+    def test_categories_consistency(self, engine):
+        """Test that all categories are valid."""
+        valid_categories = {
+            "Basic Types", "Collections", "Control Flow", "Functions",
+            "String Operations", "File Operations", "Error Handling", "Advanced Basics"
+        }
+        for category in engine.categories.keys():
+            assert category in valid_categories
+    
+    def test_related_topics_exist(self, engine):
+        """Test that all related topics exist in the knowledge base."""
+        for topic_name in engine.list_topics():
+            topic = engine.get_topic(topic_name)
+            for related_name in topic.get("related_topics", []):
+                assert engine.get_topic(related_name) is not None, \
+                    f"Related topic '{related_name}' not found for '{topic_name}'"
+
+
+class TestModuleFunctions:
+    """Test suite for module-level functions."""
+    
+    def test_get_topic_function(self):
+        """Test module-level get_topic function."""
+        topic = get_topic("Lists")
+        assert topic is not None
+        assert topic["topic"] == "Lists"
+    
+    def test_list_topics_function(self):
+        """Test module-level list_topics function."""
+        topics = list_topics()
+        assert len(topics) == 35
+    
+    def test_search_topics_function(self):
+        """Test module-level search_topics function."""
+        results = search_topics("loop")
+        assert len(results) > 0
+    
+    def test_get_random_topic_function(self):
+        """Test module-level get_random_topic function."""
+        topic = get_random_topic()
+        assert topic is not None
+        assert "topic" in topic
+    
+    def test_get_learning_path_function(self):
+        """Test module-level get_learning_path function."""
+        path = get_learning_path()
+        assert len(path) == 35
+    
+    def test_get_engine_singleton(self):
+        """Test that get_engine returns singleton."""
+        engine1 = get_engine()
+        engine2 = get_engine()
+        assert engine1 is engine2
+
+
+class TestExamples:
+    """Test that all examples are valid Python code."""
+    
+    @pytest.fixture
+    def engine(self):
+        """Create a KnowledgeEngine instance for testing."""
+        return KnowledgeEngine()
+    
+    def test_all_examples_executable(self, engine):
+        """Test that all examples can be executed."""
+        for topic_name in engine.list_topics():
+            topic = engine.get_topic(topic_name)
+            example = topic.get("example", "")
+            
+            # Try to compile the example
+            try:
+                compile(example, f"<example:{topic_name}>", "exec")
+            except SyntaxError as e:
+                pytest.fail(f"Example in '{topic_name}' has syntax error: {e}")
+    
+    def test_example_contains_output_comments(self, engine):
+        """Test that examples have output comments where appropriate."""
+        for topic_name in engine.list_topics():
+            topic = engine.get_topic(topic_name)
+            example = topic.get("example", "")
+            # Most examples should have comments with output
+            # But not all - some examples don't have print statements
+            if "print" in example and len(example) > 50:
+                # Only check for comments in longer examples with print
+                pass  # Skip this check as not all examples need comments
+
+
+class TestPerformance:
+    """Test performance requirements."""
+    
+    def test_engine_initialization_performance(self):
+        """Test that engine initializes quickly."""
+        import time
+        start = time.time()
+        engine = KnowledgeEngine()
+        elapsed = (time.time() - start) * 1000  # Convert to ms
+        assert elapsed < 100, f"Engine initialization took {elapsed}ms, should be < 100ms"
+    
+    def test_search_performance(self):
+        """Test that search is fast."""
+        import time
+        engine = KnowledgeEngine()
+        start = time.time()
+        results = engine.search_topics("loop")
+        elapsed = (time.time() - start) * 1000  # Convert to ms
+        assert elapsed < 100, f"Search took {elapsed}ms, should be < 100ms"
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

fishertools/learn/test_knowledge_engine_pbt.py

@@ -0,0 +1,180 @@
+"""
+Property-based tests for the Knowledge Engine module using Hypothesis.
+
+**Validates: Requirements 1.2-1.5, 4.1, 4.3, 5.1, 5.2**
+"""
+
+import pytest
+from hypothesis import given, strategies as st
+from fishertools.learn.knowledge_engine import KnowledgeEngine
+
+
+@pytest.fixture
+def engine():
+    """Create a KnowledgeEngine instance for testing."""
+    return KnowledgeEngine()
+
+
+class TestProperty1GetTopicStructure:
+    """Property 1: get_topic returns correct structure
+    
+    **Validates: Requirements 1.2, 2.1**
+    """
+    
+    @given(st.sampled_from(["Lists", "Variables and Assignment", "For Loops"]))
+    def test_get_topic_returns_dict_with_required_fields(self, topic_name):
+        """For any existing topic, get_topic returns dict with all required fields."""
+        engine = KnowledgeEngine()
+        topic = engine.get_topic(topic_name)
+        
+        assert topic is not None
+        assert isinstance(topic, dict)
+        assert "topic" in topic
+        assert "description" in topic
+        assert "when_to_use" in topic
+        assert "example" in topic
+        assert "common_mistakes" in topic
+        assert "related_topics" in topic
+
+
+class TestProperty2ListTopicsComplete:
+    """Property 2: list_topics returns all topics
+    
+    **Validates: Requirements 1.4**
+    """
+    
+    def test_list_topics_returns_all_loaded_topics(self):
+        """For any Knowledge Engine, list_topics returns all loaded topics."""
+        engine = KnowledgeEngine()
+        topics_list = engine.list_topics()
+        
+        # Should have exactly 35 topics
+        assert len(topics_list) == 35
+        
+        # All topics should be strings
+        assert all(isinstance(t, str) for t in topics_list)
+        
+        # All topics should be retrievable
+        for topic_name in topics_list:
+            assert engine.get_topic(topic_name) is not None
+
+
+class TestProperty3SearchTopicsRelevant:
+    """Property 3: search_topics finds relevant topics
+    
+    **Validates: Requirements 1.5**
+    """
+    
+    @given(st.sampled_from(["list", "loop", "function", "string", "error"]))
+    def test_search_topics_returns_only_relevant(self, keyword):
+        """For any keyword, search_topics returns only topics containing that keyword."""
+        engine = KnowledgeEngine()
+        results = engine.search_topics(keyword)
+        
+        # All results should contain the keyword (case-insensitive)
+        for topic_name in results:
+            topic = engine.get_topic(topic_name)
+            full_text = (
+                topic["topic"].lower() +
+                topic["description"].lower() +
+                topic["when_to_use"].lower()
+            )
+            assert keyword.lower() in full_text
+
+
+class TestProperty4RelatedTopicsExist:
+    """Property 4: get_related_topics returns existing topics
+    
+    **Validates: Requirements 1.5**
+    """
+    
+    @given(st.sampled_from(["Lists", "Variables and Assignment", "For Loops", "Functions"]))
+    def test_related_topics_all_exist(self, topic_name):
+        """For any topic, all related topics exist in the knowledge base."""
+        engine = KnowledgeEngine()
+        related = engine.get_related_topics(topic_name)
+        
+        # All related topics should exist
+        for related_name in related:
+            assert engine.get_topic(related_name) is not None
+
+
+class TestProperty5ExamplesValid:
+    """Property 5: examples are valid Python code
+    
+    **Validates: Requirements 5.1, 5.2**
+    """
+    
+    @given(st.sampled_from(["Lists", "Variables and Assignment", "For Loops", "Dictionaries"]))
+    def test_examples_are_valid_python(self, topic_name):
+        """For any topic, the example is valid Python code."""
+        engine = KnowledgeEngine()
+        topic = engine.get_topic(topic_name)
+        example = topic.get("example", "")
+        
+        # Should be compilable Python
+        try:
+            compile(example, f"<example:{topic_name}>", "exec")
+        except SyntaxError:
+            pytest.fail(f"Example in '{topic_name}' is not valid Python")
+
+
+class TestProperty6CategoriesConsistent:
+    """Property 6: categories are consistent
+    
+    **Validates: Requirements 4.1**
+    """
+    
+    def test_all_topics_have_valid_category(self):
+        """For any topic, the category is one of the valid categories."""
+        engine = KnowledgeEngine()
+        valid_categories = {
+            "Basic Types", "Collections", "Control Flow", "Functions",
+            "String Operations", "File Operations", "Error Handling", "Advanced Basics"
+        }
+        
+        for topic_name in engine.list_topics():
+            topic = engine.get_topic(topic_name)
+            assert topic["category"] in valid_categories
+
+
+class TestProperty7RelatedTopicsConsistent:
+    """Property 7: related_topics contain existing topics
+    
+    **Validates: Requirements 4.1**
+    """
+    
+    def test_all_related_topics_exist(self):
+        """For any topic, all related topics exist in the knowledge base."""
+        engine = KnowledgeEngine()
+        
+        for topic_name in engine.list_topics():
+            topic = engine.get_topic(topic_name)
+            for related_name in topic.get("related_topics", []):
+                assert engine.get_topic(related_name) is not None, \
+                    f"Related topic '{related_name}' not found for '{topic_name}'"
+
+
+class TestProperty8LearningPathOrdered:
+    """Property 8: get_learning_path returns topics in correct order
+    
+    **Validates: Requirements 4.3**
+    """
+    
+    def test_learning_path_ordered_by_difficulty(self):
+        """For any Knowledge Engine, learning path is ordered from simple to complex."""
+        engine = KnowledgeEngine()
+        path = engine.get_learning_path()
+        
+        # Should have all 35 topics
+        assert len(path) == 35
+        
+        # Should be ordered by order field
+        for i in range(len(path) - 1):
+            current_topic = engine.get_topic(path[i])
+            next_topic = engine.get_topic(path[i + 1])
+            assert current_topic["order"] <= next_topic["order"]
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

fishertools/patterns/__init__.py

@@ -0,0 +1,46 @@
+"""
+Patterns module for fishertools.
+
+This module provides reusable pattern templates for common programming tasks,
+including menu systems, data storage, logging, and command-line interfaces.
+
+Available patterns:
+- simple_menu: Interactive console menu
+- JSONStorage: JSON-based data persistence
+- SimpleLogger: Simple file-based logging
+- SimpleCLI: Command-line interface builder
+
+Example:
+    from fishertools.patterns import simple_menu, JSONStorage, SimpleLogger, SimpleCLI
+
+    # Use simple_menu
+    def greet():
+        print("Hello!")
+
+    simple_menu({"Greet": greet})
+
+    # Use JSONStorage
+    storage = JSONStorage("data.json")
+    storage.save({"name": "Alice"})
+    data = storage.load()
+
+    # Use SimpleLogger
+    logger = SimpleLogger("app.log")
+    logger.info("Application started")
+
+    # Use SimpleCLI
+    cli = SimpleCLI("myapp", "My application")
+
+    @cli.command("greet", "Greet someone")
+    def greet_cmd(name):
+        print(f"Hello, {name}!")
+
+    cli.run()
+"""
+
+from fishertools.patterns.menu import simple_menu
+from fishertools.patterns.storage import JSONStorage
+from fishertools.patterns.logger import SimpleLogger
+from fishertools.patterns.cli import SimpleCLI
+
+__all__ = ["simple_menu", "JSONStorage", "SimpleLogger", "SimpleCLI"]

fishertools/patterns/cli.py

@@ -0,0 +1,175 @@
+"""
+SimpleCLI pattern for command-line interface creation.
+
+This module provides the SimpleCLI class for creating command-line interfaces
+with minimal boilerplate code. Commands are registered via decorators and
+executed based on command-line arguments.
+
+Example:
+    cli = SimpleCLI("myapp", "My application")
+
+    @cli.command("greet", "Greet someone")
+    def greet(name):
+        print(f"Hello, {name}!")
+
+    @cli.command("goodbye", "Say goodbye")
+    def goodbye(name):
+        print(f"Goodbye, {name}!")
+
+    cli.run()
+"""
+
+
+class SimpleCLI:
+    """
+    Create command-line interfaces with minimal boilerplate.
+
+    This class provides a decorator-based system for registering commands and
+    a run() method for parsing and executing them. Supports --help flag and
+    graceful error handling.
+
+    Parameters:
+        name (str): The name of the CLI application.
+        description (str): A description of what the application does.
+
+    Attributes:
+        name (str): The application name.
+        description (str): The application description.
+
+    Methods:
+        command(name, description): Decorator to register a command.
+        run(args=None): Parse and execute commands.
+
+    Raises:
+        ValueError: If command registration fails.
+
+    Example:
+        cli = SimpleCLI("calculator", "Simple calculator")
+
+        @cli.command("add", "Add two numbers")
+        def add(a, b):
+            print(f"{a} + {b} = {int(a) + int(b)}")
+
+        @cli.command("multiply", "Multiply two numbers")
+        def multiply(a, b):
+            print(f"{a} * {b} = {int(a) * int(b)}")
+
+        cli.run()
+
+    Note:
+        - Commands are registered via @cli.command() decorator
+        - Use --help or -h to show available commands
+        - Invalid commands display an error and show help
+        - Command handlers receive arguments as strings
+        - Each command can have its own parameters
+    """
+
+    def __init__(self, name, description):
+        """
+        Initialize SimpleCLI with name and description.
+
+        Parameters:
+            name (str): The name of the CLI application.
+            description (str): A description of the application.
+        """
+        self.name = name
+        self.description = description
+        self.commands = {}
+
+    def command(self, name, description):
+        """
+        Decorator to register a command.
+
+        Parameters:
+            name (str): The command name.
+            description (str): A description of what the command does.
+
+        Returns:
+            callable: A decorator function that registers the command.
+
+        Example:
+            @cli.command("status", "Show application status")
+            def show_status():
+                print("Application is running")
+        """
+        def decorator(func):
+            self.commands[name] = {
+                "handler": func,
+                "description": description
+            }
+            return func
+        return decorator
+
+    def run(self, args=None):
+        """
+        Parse and execute commands.
+
+        Parses command-line arguments and executes the appropriate command
+        handler. Shows help on --help or invalid commands.
+
+        Parameters:
+            args (list, optional): Command-line arguments. If None, uses sys.argv[1:].
+
+        Returns:
+            None
+
+        Raises:
+            SystemExit: On --help or invalid command (after displaying message).
+
+        Example:
+            cli.run()  # Uses sys.argv
+            cli.run(["add", "5", "3"])  # Uses provided args
+        """
+        import sys
+        
+        # Use provided args or sys.argv[1:]
+        if args is None:
+            args = sys.argv[1:]
+        
+        # Handle no arguments or help flags
+        if not args or args[0] in ("--help", "-h"):
+            self._show_help()
+            return
+        
+        # Get the command name
+        command_name = args[0]
+        command_args = args[1:]
+        
+        # Check if command exists
+        if command_name not in self.commands:
+            print(f"Error: Unknown command '{command_name}'")
+            self._show_help()
+            return
+        
+        # Execute the command
+        try:
+            handler = self.commands[command_name]["handler"]
+            handler(*command_args)
+        except TypeError as e:
+            print(f"Error: Invalid arguments for command '{command_name}'")
+            print(f"Details: {e}")
+        except Exception as e:
+            print(f"Error: Command '{command_name}' failed")
+            print(f"Details: {e}")
+
+    def _show_help(self):
+        """
+        Display help information.
+
+        Shows the application name, description, and all available commands
+        with their descriptions.
+
+        Returns:
+            None
+        """
+        print(f"\n{self.name}")
+        print(f"{self.description}")
+        print("\nAvailable commands:")
+        
+        if not self.commands:
+            print("  (no commands registered)")
+        else:
+            for cmd_name, cmd_info in self.commands.items():
+                print(f"  {cmd_name:<20} {cmd_info['description']}")
+        
+        print()