Skip to content

FEATURES.md

Latest commit

 

History

History
514 lines (401 loc) · 13 KB

FEATURES.md

File metadata and controls

514 lines (401 loc) · 13 KB

Python Features Explorer - Updated Features Documentation

Overview

This document describes the new features and improvements added to the Python Features Explorer application.

New Features

1. 🔍 Search Functionality

Purpose: Quickly find specific chapters by name, description, or examples.

How to Use:

  • When the main menu displays, type a keyword at the search prompt
  • Examples: "os", "module", math
  • Press Enter to see all chapters
  • You can continue searching or exit to view all chapters

Features:

  • Searches chapter titles, descriptions, and example names
  • Configurable minimum characters (default: 2)
  • Fuzzy matching support (can be enabled in config)

2. 💾 Progress Tracking & State Persistence

Purpose: Remember your learning progress between sessions.

What Gets Saved:

  • Completed chapters
  • Examples viewed per chapter
  • Quiz scores
  • Example ratings
  • Favorited chapters
  • Total time spent
  • Last session timestamp

How to Use:

  • Progress is automatically saved after each chapter
  • Manual save through quit command
  • Load automatically on next session

Configuration:

progress:
  enabled: true
  storage_file: "user_progress.json"
  auto_save: true

3. 📊 Chapter Statistics

Purpose: Monitor your learning progress.

Access: Type stats at the main menu.

Statistics Displayed:

  • Total chapters and completed chapters
  • Progress percentage
  • Favorited chapters count
  • Examples rated
  • Last session time
  • Total time spent
  • Per-chapter example completion rates

4. ⭐ Chapter Favorites

Purpose: Mark important chapters for quick access.

How to Use:

  • Enable favorite mode: type fav
  • Browse chapters - favorites shown with ⭐
  • Toggle individual chapters using f<number>
  • Favorites appear at top of menu

Configuration:

favorites:
  enabled: true
  max_favorites: 10

5. 🌚🌞 Theme Support (Terminal Colors)

Purpose: Customizable terminal display for better readability.

Available Themes:

  • light - Light-colored output
  • dark - Dark-colored output
  • auto - Auto-detect (system default)

Color Options:

  • Header and separators: Cyan
  • Chapter titles: Green
  • Example text: Blue
  • Output messages: White
  • Error messages: Red
  • Success: Green
  • Warnings: Yellow

Installation Required:

pip install colorama

Configuration:

theme:
  mode: "auto"
  colors:
    header: "cyan"
    chapter_title: "green"
    example: "blue"

6. 📚 Chapter Quizzes

Purpose: Test your understanding after completing chapters.

Features:

  • Randomized questions from generated pool
  • Multiple choice format
  • Instant feedback with explanations
  • Pass/fail determination
  • Score tracking
  • Retry attempts allowed

How to Use:

  • Enable quizzes in config: "enabled": true
  • Type y when prompted after viewing examples
  • Answer questions displayed
  • See results and explanations

Question Generation:

  • Run python generate_quizzes.py to generate quiz files
  • Automatically extracts questions from chapter README content
  • Custom questions can be added manually

Quiz Files Location: quizzes/quiz_ch<chapter_number>.json

7. ⚙️ Configuration File Support

Purpose: Customize application behavior without modifying code.

Configuration File: config.yaml

Key Configuration Options:

App Settings

app:
  name: "Python Features Explorer"
  version: "2.0.0"
  debug: false

Execution Settings

execution:
  timeout_seconds: 30
  max_examples_per_session: 0
  shell: "python3"

Display Settings

display:
  show_descriptions: true
  show_progress_bars: true
  content_width: 80
  wide_separators: true

Search Settings

search:
  fuzzy_match: true
  min_characters: 2
  search_scope: "all"

Security Settings

security:
  sandbox_mode: false
  allowed_directories: ["examples"]
  blocked_functions: ["os.system", "eval", "exec"]

8. 🛡️ Improved Error Handling

Purpose: Better user experience when things go wrong.

New Error Classes:

  • ConfigurationError - Configuration file issues
  • ExampleExecutionError - Code execution problems
  • ChapterNotFoundError - Invalid chapter selection

Better Error Messages:

  • Context-aware error display
  • Helpful suggestions
  • Fallback behavior when possible

9. 📝 Logging System

Purpose: Track application activity for debugging and insights.

Log File: python_explorer.log

Log Entries Include:

  • Application start/end times
  • Configuration loaded
  • Chapters discovered
  • Chapter examples executed
  • User progress updates
  • Errors and warnings

Log Level Configurable:

logging:
  level: "INFO"  # DEBUG, INFO, WARNING, ERROR, CRITICAL

Usage Commands

Main Menu Commands:

  • 1-N: Select chapter
  • exit, quit, q: Exit application
  • stats: Show statistics
  • fav: Toggle favorite mode
  • help: Show available commands
  • config: Display current configuration

During Example Viewing:

  • y: Try quiz (if enabled)
  • f: Mark favorite (in favorite mode)

Installation & Setup

1. Install Dependencies

cd /home/dido/projects/python/python_quick_robert_oliver/using_math
pip install -r requirements.txt

Required:

  • colorama>=0.4.6 - Terminal colors
  • PyYAML>=6.0 - Configuration parsing

2. Configure Application

Edit config.yaml for your preferences:

  • Set color theme
  • Configure timeout
  • Customize search behavior
  • Enable/disable features

3. Generate Quizzes (Optional)

python generate_quizzes.py

This creates quiz files in the quizzes/ directory.

4. Run Application

python main.py

Feature Integration

How New Features Work Together

┌─────────────────────────────────────────────────────────┐
│                    MAIN MENU                             │
│  - Shows progress                                      │
│  - Search bar                                          │
│  - Favorites section                                   │
│  - All chapters with status indicators                │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
            ┌─────────────────────────────┐
            │    SELECT CHAPTER (1-N)     │
            └─────────────────────────────┘
                            │
                            ▼
            ┌─────────────────────────────┐
            │   CHAPTER DETAILS VIEW      │
            │  - Display content          │
            │  - List examples            │
            │  - Progress indicators      │
            └─────────────────────────────┘
                            │
                            ▼
            ┌─────────────────────────────┐
            │     RUN EXAMPLE             │
            │  - Execute code             │
            │  - Capture output           │
            │  - Track viewing            │
            │  - Timeout handling         │
            └─────────────────────────────┘
                            │
                    ┌───────┴───────┐
                    │               │
                    ▼               ▼
         ┌──────────────┐  ┌──────────────┐
         │  COMPLETE?   │  │  QUIZ?       │
         └──────────────┘  └──────────────┘
                    │               │
                    ▼               ▼
         ┌──────────────┐  ┌──────────────┐
         │ Mark Done    │  │ Answer Qs    │
         │ Update Score │  │ Track Score  │
         └──────────────┘  └──────────────┘
                          │
                     ┌────┴────┐
                     │  YES    │  NO
                     └────┬────┘
                          ▼
                  ┌──────────────┐
                  │  Continue    │
                  │   Next       │
                  └──────────────┘

Best Practices

Progress Management

  1. Complete examples sequentially - This helps track learning systematically
  2. Take quizzes - Reinforce what you've learned
  3. Bookmark favorites - Return to challenging chapters

Configuration Tips

  1. Start with defaults - Adjust settings as you learn what works for you
  2. Use dark mode - Easier on eyes for long sessions
  3. Enable auto-save - Never lose your progress

Search Best Practices

  1. Use keywords - Focus on specific terms you're learning
  2. Search examples - Find specific code patterns
  3. Combine terms - Type multiple words for broader search

Troubleshooting

Progress Not Saving

  • Check config.yaml has progress.enabled: true
  • Ensure write permissions on storage directory
  • Check user_progress.json is not read-only

Colors Not Displaying

  • Install colorama: pip install colorama
  • Check terminal supports ANSI colors
  • Try different terminal emulator

Quiz Not Appearin

  • Verify quizzes are enabled in config.yaml
  • Ensure quiz files exist in quizzes/ directory
  • Run quiz generation: python generate_quizzes.py

Example Fails to Execute

  • Check Python version compatibility (3.8+)
  • Verify example file exists and is executable
  • Check timeout value is sufficient

Application Crashes

  • Check python_explorer.log for errors
  • Try starting with config.yaml defaults
  • Ensure all requirements are installed

Updates for Version 2.0

From Version 1.0 to 2.0

Added:

  • 🔍 Search functionality
  • 💾 Progress tracking
  • ⭐ Favorites system
  • 📊 Statistics display
  • 🌚 Dark mode support
  • 📚 Quiz functionality
  • ⚙️ Configuration support
  • 📝 Logging system

Improved:

  • Error handling and messages
  • Input validation
  • Session persistence
  • User experience flow
  • Code organization

Performance:

  • Added result caching
  • Optimized file loading
  • Reduced memory footprint
  • Faster search operations

Security Considerations

Current Security Model

  • No sandboxing by default - Examples execute with full privileges
  • File path validation - Only allows execution of .py files
  • Timeout protection - Prevents infinite loops
  • Configurable execution - Can restrict to specific directories

Recommended for Production

  1. Enable sandbox mode in config (sandbox_mode: true)
  2. Review allowed_directories carefully
  3. Monitor blocked_functions list
  4. Log all executions for audit trail

Known Limitations

  • Examples run with user's privileges
  • No file system sandboxing (requires external tool)
  • Network access not restricted

Future Enhancements

Planned Features (Not Yet Implemented)

  • Video tutorial integration
  • Interactive documentation viewer
  • Group/quizzes for team learning
  • Performance benchmarking
  • Community contribution system
  • Multi-language support
  • Mobile companion app
  • Progress analytics dashboard

Community Requests

  • Dark/light theme toggle on the fly
  • Export progress as PDF
  • Chapter difficulty ratings
  • Estimated time to completion
  • Bookmark specific code snippets

Support

Documentation Files

  • README.md - Main project documentation
  • docs/ - Additional documentation
  • config.yaml.example - Template configuration

Getting Help

  1. Check python_explorer.log for errors
  2. Review relevant documentation
  3. Verify configuration settings
  4. Check example Python version compatibility

Reporting Issues

When reporting issues, include:

  • Error messages from log file
  • Configuration settings used
  • Steps to reproduce
  • Python version
  • Operating system

Version History

Version 2.0.0 (Current)

Release Date: April 2024

  • Search functionality
  • Progress tracking
  • Theme support
  • Quiz system
  • Configuration file support
  • Enhanced error handling
  • Statistics display

Version 1.0

  • Initial release
  • Basic chapter navigation
  • Example execution
  • Manual state persistence

Last updated: April 2024