Jupyter Lab Progress

A comprehensive Python library for creating interactive lab exercises in Jupyter notebooks. Designed for educators, workshop leaders, and content creators who want to build engaging, validated learning experiences.

🚀 Features

• 📊 Progress Tracking: Visual progress bars, step completion tracking, persistence support
• ✅ Comprehensive Validation: Variable, function, output, DataFrame, and custom validation methods
• 🎨 Rich Display Utilities: Info boxes, warnings, code blocks, tables, tabs, hints, and more
• 💾 Persistence: Save and restore progress across sessions
• 🔗 Seamless Integration: Validators automatically update progress trackers
• 🎓 Education-Focused: Built specifically for teaching and learning scenarios

📦 Installation

pip install jupyter-lab-progress

For development installation:

git clone https://github.com/mrlynn/jupyter-lab-progress.git
cd jupyter-lab-progress/jupyter-lab-progress
pip install -e ".[dev]"

🏃‍♂️ Quick Start

from jupyter_lab_progress import LabProgress, LabValidator, show_info, show_success

# Create a progress tracker
progress = LabProgress(["Load Data", "Process Data", "Analyze Results"], 
                      lab_name="Data Science Lab")

# Create a validator linked to progress
validator = LabValidator(progress_tracker=progress)

# Show instructions
show_info("Let's start by loading the dataset", title="Step 1")

# Validate and mark progress
data_loaded = True  # Your actual condition
validator.validate_and_mark_complete("Load Data", data_loaded)

# Display success message
show_success("Great job! Data loaded successfully")

📚 Core Components

1. Progress Tracking (LabProgress)

Track student progress through lab exercises with visual feedback:

from jupyter_lab_progress import LabProgress

# Basic usage
progress = LabProgress(["Step 1", "Step 2", "Step 3"])
progress.mark_done("Step 1")

# Advanced features
progress = LabProgress(
    steps=["Load Data", "Clean Data", "Analyze"],
    lab_name="Data Analysis Lab",
    persist=True  # Save progress to file
)

# Mark with score and notes
progress.mark_done("Load Data", score=95, notes="Excellent work!")

# Partial progress
progress.mark_partial("Clean Data", 0.75)  # 75% complete

2. Validation Framework (LabValidator)

Comprehensive validation methods for checking student work:

from jupyter_lab_progress import LabValidator

validator = LabValidator()

# Variable validation
validator.validate_variable_exists("my_var", globals(), expected_type=list)

# Function validation
validator.validate_function_exists("process_data", globals(), 
                                 expected_params=["data", "method"])

# DataFrame validation
validator.validate_dataframe(df, 
                           expected_shape=(100, 5),
                           expected_columns=["id", "name", "value"])

# Custom validation with auto-progress updates
validator = LabValidator(progress_tracker=progress)
validator.validate_and_mark_complete("Step 1", condition=True)

3. Display Utilities

Rich display functions for better communication:

from jupyter_lab_progress import *

# Messages
show_info("This is informational")
show_success("Well done!")
show_warning("Be careful")
show_error("Something went wrong")

# Code display
show_code("print('Hello World')", language="python", title="Example")

# Interactive elements
show_hint("Try using pandas read_csv function")
show_progress_bar(3, 10, label="Overall Progress")
show_checklist({"Task 1": True, "Task 2": False})

# Data display 
show_json({"key": "value"}, title="Results")
show_table(headers=["Name", "Score"], rows=[["Alice", "95"]])

🔧 Advanced Usage

Custom Validators

# Create step-specific validators
validator = LabValidator(progress_tracker=progress)
validate_step1 = validator.create_step_validator("Step 1")

# Use custom validation
result = compute_something()
validate_step1(result == expected_value, 
               success_msg="Perfect calculation!",
               failure_msg="Check your math")

Persistence

# Progress automatically saves/loads
progress = LabProgress(steps, persist=True, persist_file="my_lab.json")

Integration Example

from jupyter_lab_progress import *

# Complete lab setup
steps = ["Import Libraries", "Load Data", "Preprocess", "Train Model"]
progress = LabProgress(steps, lab_name="ML Workshop", persist=True)
validator = LabValidator(progress_tracker=progress)

# Step 1: Instructions
show_info("First, import required libraries", title="Step 1")
show_code("import pandas as pd\\nimport numpy as np")

# Validation with auto-progress
try:
    import pandas as pd
    import numpy as np
    validator.validate_and_mark_complete("Import Libraries", True)
except ImportError:
    show_error("Missing libraries. Run: pip install pandas numpy")

🎯 Use Cases

• Educational Workshops: Interactive coding workshops with guided exercises
• Corporate Training: Employee training programs with progress tracking
• Online Courses: Self-paced learning with automated validation
• Data Science Bootcamps: Hands-on exercises with immediate feedback
• Research Training: Academic lab exercises with validation

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

git clone https://github.com/mrlynn/jupyter-lab-utils.git
cd jupyter-lab-utils/jupyter-lab-progress
pip install -e ".[dev]"
pre-commit install

Running Tests

pytest
pytest --cov=jupyter_lab_progress --cov-report=html

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: https://github.com/mrlynn/jupyter-lab-utils#readme
• Issues: GitHub Issues
• Discussions: GitHub Discussions

🏗️ Built by Michael Lynn https://mlynn.org

Created with ❤️ by the MongoDB Developer Relations team to enhance the learning experience in data science and development workshops.

---

Happy Teaching and Learning! 🎓