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

fishertools/input_utils.py

@@ -0,0 +1,185 @@
+"""
+Safe input collection module for fishertools.
+
+This module provides validated input collection functions with automatic type checking
+and range validation. It helps beginners collect user input safely without writing
+repetitive validation code.
+
+Functions:
+    ask_int() - Prompt user for an integer with optional range validation
+    ask_float() - Prompt user for a float with optional range validation
+    ask_str() - Prompt user for a string with optional length validation
+    ask_choice() - Prompt user to choose from a list of options
+"""
+
+from typing import List, Optional, Any
+
+
+def ask_int(prompt: str, min: Optional[int] = None, max: Optional[int] = None) -> int:
+    """
+    Prompt user for an integer with optional range validation.
+    
+    Args:
+        prompt: The prompt to display to the user
+        min: Minimum allowed value (inclusive), optional
+        max: Maximum allowed value (inclusive), optional
+        
+    Returns:
+        Validated integer from user input
+        
+    Raises:
+        EOFError: If user provides EOF (Ctrl+D)
+        
+    Example:
+        >>> age = ask_int("How old are you? ", min=0, max=150)
+        >>> score = ask_int("Enter your score: ")
+    """
+    while True:
+        try:
+            user_input = input(prompt)
+            value = int(user_input)
+            
+            # Check min constraint
+            if min is not None and value < min:
+                print(f"Error: Value must be at least {min}")
+                continue
+            
+            # Check max constraint
+            if max is not None and value > max:
+                print(f"Error: Value must be at most {max}")
+                continue
+            
+            return value
+        except ValueError:
+            print(f"Error: Please enter a valid integer")
+        except EOFError:
+            raise
+
+
+def ask_float(prompt: str, min: Optional[float] = None, max: Optional[float] = None) -> float:
+    """
+    Prompt user for a float with optional range validation.
+    
+    Args:
+        prompt: The prompt to display to the user
+        min: Minimum allowed value (inclusive), optional
+        max: Maximum allowed value (inclusive), optional
+        
+    Returns:
+        Validated float from user input
+        
+    Raises:
+        EOFError: If user provides EOF (Ctrl+D)
+        
+    Example:
+        >>> temperature = ask_float("Enter temperature (C): ", min=-273.15)
+        >>> price = ask_float("Enter price: ", min=0)
+    """
+    while True:
+        try:
+            user_input = input(prompt)
+            value = float(user_input)
+            
+            # Check min constraint
+            if min is not None and value < min:
+                print(f"Error: Value must be at least {min}")
+                continue
+            
+            # Check max constraint
+            if max is not None and value > max:
+                print(f"Error: Value must be at most {max}")
+                continue
+            
+            return value
+        except ValueError:
+            print(f"Error: Please enter a valid number")
+        except EOFError:
+            raise
+
+
+def ask_str(prompt: str, min_length: Optional[int] = None, max_length: Optional[int] = None) -> str:
+    """
+    Prompt user for a string with optional length validation.
+    
+    Args:
+        prompt: The prompt to display to the user
+        min_length: Minimum string length, optional
+        max_length: Maximum string length, optional
+        
+    Returns:
+        Validated string from user input (whitespace stripped)
+        
+    Raises:
+        EOFError: If user provides EOF (Ctrl+D)
+        
+    Example:
+        >>> name = ask_str("Enter your name: ", min_length=1, max_length=50)
+        >>> password = ask_str("Enter password: ", min_length=8)
+    """
+    while True:
+        try:
+            user_input = input(prompt)
+            value = user_input.strip()
+            
+            # Check min_length constraint
+            if min_length is not None and len(value) < min_length:
+                print(f"Error: String must be at least {min_length} characters long")
+                continue
+            
+            # Check max_length constraint
+            if max_length is not None and len(value) > max_length:
+                print(f"Error: String must be at most {max_length} characters long")
+                continue
+            
+            return value
+        except EOFError:
+            raise
+
+
+def ask_choice(prompt: str, options: List[str]) -> str:
+    """
+    Prompt user to choose from a list of options.
+    
+    Args:
+        prompt: The prompt to display to the user
+        options: List of available choices
+        
+    Returns:
+        The selected option (exact string from options list)
+        
+    Raises:
+        EOFError: If user provides EOF (Ctrl+D)
+        ValueError: If options list is empty
+        
+    Example:
+        >>> color = ask_choice("Choose a color: ", ["red", "green", "blue"])
+        >>> choice = ask_choice("Select: ", ["Yes", "No", "Maybe"])
+    """
+    if not options:
+        raise ValueError("Options list cannot be empty")
+    
+    while True:
+        try:
+            # Display options
+            for i, option in enumerate(options, 1):
+                print(f"  {i}. {option}")
+            
+            user_input = input(prompt).strip()
+            
+            # Try numeric selection first
+            try:
+                choice_index = int(user_input) - 1
+                if 0 <= choice_index < len(options):
+                    return options[choice_index]
+                else:
+                    print(f"Error: Please enter a number between 1 and {len(options)}")
+                    continue
+            except ValueError:
+                # Try direct text matching
+                if user_input in options:
+                    return user_input
+                else:
+                    print(f"Error: '{user_input}' is not a valid option")
+                    continue
+        except EOFError:
+            raise

fishertools/learn/__init__.py

@@ -5,14 +5,31 @@ This module provides educational utilities that help beginners
 learn Python best practices and concepts.
 """
 
-from .examples import generate_example, list_available_concepts, get_concept_info
+from .examples import generate_example, list_available_concepts, get_concept_info, explain
 from .tips import show_best_practice, list_available_topics, get_topic_summary
+from .knowledge_engine import (
+    KnowledgeEngine,
+    get_topic,
+    list_topics,
+    search_topics,
+    get_random_topic,
+    get_learning_path,
+    get_engine
+)
 
 __all__ = [
     "generate_example", 
     "list_available_concepts", 
     "get_concept_info",
+    "explain",
     "show_best_practice", 
     "list_available_topics", 
-    "get_topic_summary"
+    "get_topic_summary",
+    "KnowledgeEngine",
+    "get_topic",
+    "list_topics",
+    "search_topics",
+    "get_random_topic",
+    "get_learning_path",
+    "get_engine"
 ]

fishertools/learn/examples.py

@@ -5,6 +5,8 @@ This module contains functions to generate educational code examples
 for common Python concepts that beginners need to learn.
 """
 
+import json
+import os
 from typing import Dict, Optional
 
 
@@ -547,4 +549,89 @@ def get_concept_info(concept: str) -> Optional[Dict[str, str]]:
     return {
         "title": CODE_EXAMPLES[concept_lower]["title"],
         "description": CODE_EXAMPLES[concept_lower]["description"]
-    }
+    }
+
+
+
+def explain(topic: str) -> Dict[str, str]:
+    """
+    Get a structured explanation for a Python topic.
+    
+    This function loads explanations from the explanations.json file and returns
+    a dictionary containing a description, usage guidance, and code example for
+    the requested topic.
+    
+    Parameters
+    ----------
+    topic : str
+        The name of the Python topic to explain (e.g., 'list', 'for', 'lambda').
+        Topic names are case-insensitive.
+    
+    Returns
+    -------
+    dict
+        A dictionary with the following keys:
+        - 'description' (str): A clear, concise explanation of what the topic is
+        - 'when_to_use' (str): Practical guidance on when to use this topic
+        - 'example' (str): Valid, runnable Python code demonstrating the topic
+    
+    Raises
+    ------
+    ValueError
+        If the topic is not found in the explanations database. The error message
+        includes a helpful list of all available topics.
+    FileNotFoundError
+        If the explanations.json file cannot be found.
+    json.JSONDecodeError
+        If the explanations.json file is corrupted or invalid.
+    
+    Examples
+    --------
+    >>> explanation = explain('list')
+    >>> print(explanation['description'])
+    Ordered collection of items that can be of different types...
+    
+    >>> explanation = explain('lambda')
+    >>> print(explanation['example'])
+    square = lambda x: x ** 2
+    print(square(5))
+    
+    >>> try:
+    ...     explain('invalid_topic')
+    ... except ValueError as e:
+    ...     print(str(e))
+    Topic 'invalid_topic' not found. Available topics: int, float, str, ...
+    """
+    # Normalize the topic name
+    topic_normalized = topic.strip().lower()
+    
+    # Get the path to the explanations.json file
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    explanations_path = os.path.join(current_dir, 'explanations.json')
+    
+    # Load the explanations from JSON file
+    try:
+        with open(explanations_path, 'r', encoding='utf-8') as f:
+            explanations = json.load(f)
+    except FileNotFoundError:
+        raise FileNotFoundError(
+            f"Explanations file not found at {explanations_path}. "
+            "Please ensure explanations.json is in the fishertools/learn/ directory."
+        )
+    except json.JSONDecodeError as e:
+        raise json.JSONDecodeError(
+            f"Failed to parse explanations.json: {e.msg}",
+            e.doc,
+            e.pos
+        )
+    
+    # Check if the topic exists
+    if topic_normalized not in explanations:
+        available_topics = sorted(explanations.keys())
+        topics_str = ", ".join(available_topics)
+        raise ValueError(
+            f"Topic '{topic}' not found. Available topics: {topics_str}"
+        )
+    
+    # Return the explanation dictionary
+    return explanations[topic_normalized]

fishertools/learn/knowledge_engine.py

@@ -0,0 +1,321 @@
+"""
+Knowledge Engine for fishertools - Educational system for Python concepts.
+
+This module provides a structured knowledge base of Python concepts for beginners,
+with explanations, examples, common mistakes, and related topics.
+"""
+
+import json
+import os
+import random
+from typing import Dict, List, Optional
+
+
+class KnowledgeEngine:
+    """
+    Knowledge Engine for managing and accessing educational content about Python concepts.
+    
+    The engine loads topics from a JSON file and provides methods to search, filter,
+    and retrieve information about Python concepts for beginners.
+    
+    Attributes:
+        topics (Dict[str, Dict]): Dictionary of all loaded topics indexed by name
+        categories (Dict[str, List[str]]): Dictionary mapping categories to topic names
+    
+    Example:
+        >>> engine = KnowledgeEngine()
+        >>> topic = engine.get_topic("Lists")
+        >>> print(topic["description"])
+        >>> all_topics = engine.list_topics()
+        >>> related = engine.get_related_topics("Lists")
+    """
+    
+    def __init__(self, topics_file: Optional[str] = None):
+        """
+        Initialize the Knowledge Engine by loading topics from a JSON file.
+        
+        Args:
+            topics_file: Path to the JSON file containing topics. If None, uses default location.
+        
+        Raises:
+            FileNotFoundError: If the topics file is not found
+            ValueError: If the JSON file is invalid or corrupted
+        
+        Example:
+            >>> engine = KnowledgeEngine()
+            >>> engine = KnowledgeEngine("custom_topics.json")
+        """
+        if topics_file is None:
+            # Use default location relative to this file
+            topics_file = os.path.join(os.path.dirname(__file__), "topics.json")
+        
+        if not os.path.exists(topics_file):
+            raise FileNotFoundError(f"Topics file not found: {topics_file}")
+        
+        try:
+            with open(topics_file, 'r', encoding='utf-8') as f:
+                topics_list = json.load(f)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON in topics file: {e}")
+        
+        # Index topics by name for fast lookup
+        self.topics: Dict[str, Dict] = {}
+        self.categories: Dict[str, List[str]] = {}
+        
+        for topic in topics_list:
+            topic_name = topic.get("topic")
+            if not topic_name:
+                raise ValueError("Topic missing 'topic' field")
+            
+            self.topics[topic_name] = topic
+            
+            # Index by category
+            category = topic.get("category", "Uncategorized")
+            if category not in self.categories:
+                self.categories[category] = []
+            self.categories[category].append(topic_name)
+    
+    def get_topic(self, name: str) -> Optional[Dict]:
+        """
+        Get a topic by name.
+        
+        Args:
+            name: The name of the topic to retrieve
+        
+        Returns:
+            Dictionary containing the topic information, or None if not found
+        
+        Example:
+            >>> engine = KnowledgeEngine()
+            >>> topic = engine.get_topic("Lists")
+            >>> if topic:
+            ...     print(topic["description"])
+        """
+        return self.topics.get(name)
+    
+    def list_topics(self) -> List[str]:
+        """
+        Get a list of all available topics.
+        
+        Returns:
+            Sorted list of all topic names
+        
+        Example:
+            >>> engine = KnowledgeEngine()
+            >>> topics = engine.list_topics()
+            >>> print(f"Available topics: {len(topics)}")
+        """
+        return sorted(self.topics.keys())
+    
+    def search_topics(self, keyword: str) -> List[str]:
+        """
+        Search for topics containing a keyword in name or description.
+        
+        The search is case-insensitive and matches partial words.
+        
+        Args:
+            keyword: The keyword to search for
+        
+        Returns:
+            List of topic names matching the keyword
+        
+        Example:
+            >>> engine = KnowledgeEngine()
+            >>> results = engine.search_topics("list")
+            >>> print(f"Found {len(results)} topics about lists")
+        """
+        keyword_lower = keyword.lower()
+        results = []
+        
+        for name, topic in self.topics.items():
+            # Search in topic name
+            if keyword_lower in name.lower():
+                results.append(name)
+                continue
+            
+            # Search in description
+            description = topic.get("description", "").lower()
+            if keyword_lower in description:
+                results.append(name)
+                continue
+            
+            # Search in when_to_use
+            when_to_use = topic.get("when_to_use", "").lower()
+            if keyword_lower in when_to_use:
+                results.append(name)
+        
+        return sorted(results)
+    
+    def get_random_topic(self) -> Dict:
+        """
+        Get a random topic for learning.
+        
+        Returns:
+            A randomly selected topic dictionary
+        
+        Example:
+            >>> engine = KnowledgeEngine()
+            >>> topic = engine.get_random_topic()
+            >>> print(f"Today's topic: {topic['topic']}")
+        """
+        topic_name = random.choice(list(self.topics.keys()))
+        return self.topics[topic_name]
+    
+    def get_related_topics(self, topic_name: str) -> List[str]:
+        """
+        Get topics related to a given topic.
+        
+        Args:
+            topic_name: The name of the topic
+        
+        Returns:
+            List of related topic names that exist in the knowledge base
+        
+        Example:
+            >>> engine = KnowledgeEngine()
+            >>> related = engine.get_related_topics("Lists")
+            >>> print(f"Related topics: {related}")
+        """
+        topic = self.get_topic(topic_name)
+        if not topic:
+            return []
+        
+        related = topic.get("related_topics", [])
+        # Filter to only include topics that exist in the knowledge base
+        return [t for t in related if t in self.topics]
+    
+    def get_topics_by_category(self, category: str) -> List[str]:
+        """
+        Get all topics in a specific category.
+        
+        Args:
+            category: The category name
+        
+        Returns:
+            Sorted list of topic names in the category
+        
+        Example:
+            >>> engine = KnowledgeEngine()
+            >>> basic_types = engine.get_topics_by_category("Basic Types")
+            >>> print(f"Topics in Basic Types: {basic_types}")
+        """
+        return sorted(self.categories.get(category, []))
+    
+    def get_learning_path(self) -> List[str]:
+        """
+        Get the recommended learning path from simple to complex topics.
+        
+        Returns:
+            List of topic names ordered by difficulty
+        
+        Example:
+            >>> engine = KnowledgeEngine()
+            >>> path = engine.get_learning_path()
+            >>> for topic_name in path:
+            ...     print(topic_name)
+        """
+        # Sort topics by order field, then by difficulty
+        sorted_topics = sorted(
+            self.topics.items(),
+            key=lambda x: (x[1].get("order", 999), x[1].get("difficulty", ""))
+        )
+        return [name for name, _ in sorted_topics]
+
+
+# Global engine instance
+_engine: Optional[KnowledgeEngine] = None
+
+
+def get_engine() -> KnowledgeEngine:
+    """
+    Get the global Knowledge Engine instance.
+    
+    Returns:
+        The global KnowledgeEngine instance
+    
+    Example:
+        >>> engine = get_engine()
+        >>> topics = engine.list_topics()
+    """
+    global _engine
+    if _engine is None:
+        _engine = KnowledgeEngine()
+    return _engine
+
+
+def get_topic(name: str) -> Optional[Dict]:
+    """
+    Get a topic by name using the global engine.
+    
+    Args:
+        name: The name of the topic
+    
+    Returns:
+        Topic dictionary or None if not found
+    
+    Example:
+        >>> topic = get_topic("Lists")
+        >>> if topic:
+        ...     print(topic["description"])
+    """
+    return get_engine().get_topic(name)
+
+
+def list_topics() -> List[str]:
+    """
+    Get a list of all available topics using the global engine.
+    
+    Returns:
+        Sorted list of all topic names
+    
+    Example:
+        >>> topics = list_topics()
+        >>> print(f"Total topics: {len(topics)}")
+    """
+    return get_engine().list_topics()
+
+
+def search_topics(keyword: str) -> List[str]:
+    """
+    Search for topics by keyword using the global engine.
+    
+    Args:
+        keyword: The keyword to search for
+    
+    Returns:
+        List of matching topic names
+    
+    Example:
+        >>> results = search_topics("loop")
+        >>> print(f"Found {len(results)} topics about loops")
+    """
+    return get_engine().search_topics(keyword)
+
+
+def get_random_topic() -> Dict:
+    """
+    Get a random topic using the global engine.
+    
+    Returns:
+        A randomly selected topic dictionary
+    
+    Example:
+        >>> topic = get_random_topic()
+        >>> print(f"Random topic: {topic['topic']}")
+    """
+    return get_engine().get_random_topic()
+
+
+def get_learning_path() -> List[str]:
+    """
+    Get the recommended learning path using the global engine.
+    
+    Returns:
+        List of topic names ordered by difficulty
+    
+    Example:
+        >>> path = get_learning_path()
+        >>> for topic_name in path[:5]:
+        ...     print(topic_name)
+    """
+    return get_engine().get_learning_path()

fishertools/learn/repl/__init__.py

@@ -0,0 +1,19 @@
+"""
+Knowledge Engine Interactive REPL - An interactive command-line interface for exploring Python topics.
+
+This package provides a beginner-friendly REPL for the Knowledge Engine that enables:
+- Topic browsing and discovery
+- Code execution in a safe sandbox
+- Learning progress tracking
+- Contextual hints and guidance
+"""
+
+def get_repl_engine():
+    """Get a REPL engine instance."""
+    from fishertools.learn.repl.engine import REPLEngine
+    return REPLEngine()
+
+
+__all__ = [
+    "get_repl_engine",
+]

fishertools/learn/repl/cli.py

@@ -0,0 +1,31 @@
+"""
+Command-line interface entry point for the Knowledge Engine REPL.
+
+This module provides the main entry point for running the REPL from the command line.
+"""
+
+import sys
+from fishertools.learn.repl.engine import REPLEngine
+
+
+def main() -> int:
+    """
+    Main entry point for the REPL.
+    
+    Returns:
+        Exit code (0 for success, 1 for error)
+    """
+    try:
+        engine = REPLEngine()
+        engine.start()
+        return 0
+    except KeyboardInterrupt:
+        print("\n\n👋 Goodbye!")
+        return 0
+    except Exception as e:
+        print(f"❌ Error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())