# Jupyter Lab Utils
[](https://badge.fury.io/py/jupyter-lab-utils)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
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
```bash
pip install jupyter-lab-utils
```
For development installation:
```bash
git clone https://github.com/mongodb/jupyter-lab-utils.git
cd jupyter-lab-utils
pip install -e ".[dev]"
```
## 🏃♂️ Quick Start
```python
from jupyter_lab_utils 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:
```python
from jupyter_lab_utils 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:
```python
from jupyter_lab_utils 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:
```python
from jupyter_lab_utils 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
```python
# 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
```python
# Progress automatically saves/loads
progress = LabProgress(steps, persist=True, persist_file="my_lab.json")
```
### Integration Example
```python
from jupyter_lab_utils 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](CONTRIBUTING.md) for details.
### Development Setup
```bash
git clone https://github.com/mongodb/jupyter-lab-utils.git
cd jupyter-lab-utils
pip install -e ".[dev]"
pre-commit install
```
### Running Tests
```bash
pytest
pytest --cov=jupyter_lab_utils --cov-report=html
```
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🆘 Support
- **Documentation**: [https://jupyter-lab-utils.readthedocs.io/](https://jupyter-lab-utils.readthedocs.io/)
- **Issues**: [GitHub Issues](https://github.com/mongodb/jupyter-lab-utils/issues)
- **Discussions**: [GitHub Discussions](https://github.com/mongodb/jupyter-lab-utils/discussions)
## 🏗️ Built by MongoDB Developer Relations
Created with ❤️ by the MongoDB Developer Relations team to enhance the learning experience in data science and development workshops.
---
**Happy Teaching and Learning!** 🎓
Raw data
{
"_id": null,
"home_page": null,
"name": "jupyter-lab-utils-mrlynn",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "jupyter, notebook, education, lab, validation, progress, interactive, teaching, workshop, tutorial",
"author": null,
"author_email": "Michael Lynn <michael.lynn@mongodb.com>",
"download_url": "https://files.pythonhosted.org/packages/40/d8/b65c290faac631ed85c48b3a6c69877362b1ba074e6350810d3477bec468/jupyter_lab_utils_mrlynn-1.0.0.tar.gz",
"platform": null,
"description": "# Jupyter Lab Utils\n\n[](https://badge.fury.io/py/jupyter-lab-utils)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nA 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.\n\n## \ud83d\ude80 Features\n\n- **\ud83d\udcca Progress Tracking**: Visual progress bars, step completion tracking, persistence support\n- **\u2705 Comprehensive Validation**: Variable, function, output, DataFrame, and custom validation methods\n- **\ud83c\udfa8 Rich Display Utilities**: Info boxes, warnings, code blocks, tables, tabs, hints, and more\n- **\ud83d\udcbe Persistence**: Save and restore progress across sessions\n- **\ud83d\udd17 Seamless Integration**: Validators automatically update progress trackers\n- **\ud83c\udf93 Education-Focused**: Built specifically for teaching and learning scenarios\n\n## \ud83d\udce6 Installation\n\n```bash\npip install jupyter-lab-utils\n```\n\nFor development installation:\n\n```bash\ngit clone https://github.com/mongodb/jupyter-lab-utils.git\ncd jupyter-lab-utils\npip install -e \".[dev]\"\n```\n\n## \ud83c\udfc3\u200d\u2642\ufe0f Quick Start\n\n```python\nfrom jupyter_lab_utils import LabProgress, LabValidator, show_info, show_success\n\n# Create a progress tracker\nprogress = LabProgress([\"Load Data\", \"Process Data\", \"Analyze Results\"], \n lab_name=\"Data Science Lab\")\n\n# Create a validator linked to progress\nvalidator = LabValidator(progress_tracker=progress)\n\n# Show instructions\nshow_info(\"Let's start by loading the dataset\", title=\"Step 1\")\n\n# Validate and mark progress\ndata_loaded = True # Your actual condition\nvalidator.validate_and_mark_complete(\"Load Data\", data_loaded)\n\n# Display success message\nshow_success(\"Great job! Data loaded successfully\")\n```\n\n## \ud83d\udcda Core Components\n\n### 1. Progress Tracking (`LabProgress`)\n\nTrack student progress through lab exercises with visual feedback:\n\n```python\nfrom jupyter_lab_utils import LabProgress\n\n# Basic usage\nprogress = LabProgress([\"Step 1\", \"Step 2\", \"Step 3\"])\nprogress.mark_done(\"Step 1\")\n\n# Advanced features\nprogress = LabProgress(\n steps=[\"Load Data\", \"Clean Data\", \"Analyze\"],\n lab_name=\"Data Analysis Lab\",\n persist=True # Save progress to file\n)\n\n# Mark with score and notes\nprogress.mark_done(\"Load Data\", score=95, notes=\"Excellent work!\")\n\n# Partial progress\nprogress.mark_partial(\"Clean Data\", 0.75) # 75% complete\n```\n\n### 2. Validation Framework (`LabValidator`)\n\nComprehensive validation methods for checking student work:\n\n```python\nfrom jupyter_lab_utils import LabValidator\n\nvalidator = LabValidator()\n\n# Variable validation\nvalidator.validate_variable_exists(\"my_var\", globals(), expected_type=list)\n\n# Function validation\nvalidator.validate_function_exists(\"process_data\", globals(), \n expected_params=[\"data\", \"method\"])\n\n# DataFrame validation\nvalidator.validate_dataframe(df, \n expected_shape=(100, 5),\n expected_columns=[\"id\", \"name\", \"value\"])\n\n# Custom validation with auto-progress updates\nvalidator = LabValidator(progress_tracker=progress)\nvalidator.validate_and_mark_complete(\"Step 1\", condition=True)\n```\n\n### 3. Display Utilities\n\nRich display functions for better communication:\n\n```python\nfrom jupyter_lab_utils import *\n\n# Messages\nshow_info(\"This is informational\")\nshow_success(\"Well done!\")\nshow_warning(\"Be careful\")\nshow_error(\"Something went wrong\")\n\n# Code display\nshow_code(\"print('Hello World')\", language=\"python\", title=\"Example\")\n\n# Interactive elements\nshow_hint(\"Try using pandas read_csv function\")\nshow_progress_bar(3, 10, label=\"Overall Progress\")\nshow_checklist({\"Task 1\": True, \"Task 2\": False})\n\n# Data display\nshow_json({\"key\": \"value\"}, title=\"Results\")\nshow_table(headers=[\"Name\", \"Score\"], rows=[[\"Alice\", \"95\"]])\n```\n\n## \ud83d\udd27 Advanced Usage\n\n### Custom Validators\n\n```python\n# Create step-specific validators\nvalidator = LabValidator(progress_tracker=progress)\nvalidate_step1 = validator.create_step_validator(\"Step 1\")\n\n# Use custom validation\nresult = compute_something()\nvalidate_step1(result == expected_value, \n success_msg=\"Perfect calculation!\",\n failure_msg=\"Check your math\")\n```\n\n### Persistence\n\n```python\n# Progress automatically saves/loads\nprogress = LabProgress(steps, persist=True, persist_file=\"my_lab.json\")\n```\n\n### Integration Example\n\n```python\nfrom jupyter_lab_utils import *\n\n# Complete lab setup\nsteps = [\"Import Libraries\", \"Load Data\", \"Preprocess\", \"Train Model\"]\nprogress = LabProgress(steps, lab_name=\"ML Workshop\", persist=True)\nvalidator = LabValidator(progress_tracker=progress)\n\n# Step 1: Instructions\nshow_info(\"First, import required libraries\", title=\"Step 1\")\nshow_code(\"import pandas as pd\\\\nimport numpy as np\")\n\n# Validation with auto-progress\ntry:\n import pandas as pd\n import numpy as np\n validator.validate_and_mark_complete(\"Import Libraries\", True)\nexcept ImportError:\n show_error(\"Missing libraries. Run: pip install pandas numpy\")\n```\n\n## \ud83c\udfaf Use Cases\n\n- **Educational Workshops**: Interactive coding workshops with guided exercises\n- **Corporate Training**: Employee training programs with progress tracking\n- **Online Courses**: Self-paced learning with automated validation\n- **Data Science Bootcamps**: Hands-on exercises with immediate feedback\n- **Research Training**: Academic lab exercises with validation\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\ngit clone https://github.com/mongodb/jupyter-lab-utils.git\ncd jupyter-lab-utils\npip install -e \".[dev]\"\npre-commit install\n```\n\n### Running Tests\n\n```bash\npytest\npytest --cov=jupyter_lab_utils --cov-report=html\n```\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83c\udd98 Support\n\n- **Documentation**: [https://jupyter-lab-utils.readthedocs.io/](https://jupyter-lab-utils.readthedocs.io/)\n- **Issues**: [GitHub Issues](https://github.com/mongodb/jupyter-lab-utils/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/mongodb/jupyter-lab-utils/discussions)\n\n## \ud83c\udfd7\ufe0f Built by MongoDB Developer Relations\n\nCreated with \u2764\ufe0f by the MongoDB Developer Relations team to enhance the learning experience in data science and development workshops.\n\n---\n\n**Happy Teaching and Learning!** \ud83c\udf93\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive toolkit for creating interactive Jupyter notebook lab exercises with progress tracking, validation, and rich display utilities.",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/mrlynn/jupyter-lab-utils/issues",
"Changelog": "https://github.com/mrlynn/jupyter-lab-utils/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/mrlynn/jupyter-lab-utils#readme",
"Homepage": "https://github.com/mrlynn/jupyter-lab-utils",
"Repository": "https://github.com/mrlynn/jupyter-lab-utils.git"
},
"split_keywords": [
"jupyter",
" notebook",
" education",
" lab",
" validation",
" progress",
" interactive",
" teaching",
" workshop",
" tutorial"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3af5b16111a10781778cf38be4b78823a46e92987a8f702a3f2008cb2908c2c5",
"md5": "53c6477427f65469e57885ba1bc6bc5d",
"sha256": "9ae90f42aff13e4158cda919d658df63954a581f3d9dd30e851a9ae71560bd29"
},
"downloads": -1,
"filename": "jupyter_lab_utils_mrlynn-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "53c6477427f65469e57885ba1bc6bc5d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 14995,
"upload_time": "2025-07-10T11:33:47",
"upload_time_iso_8601": "2025-07-10T11:33:47.255145Z",
"url": "https://files.pythonhosted.org/packages/3a/f5/b16111a10781778cf38be4b78823a46e92987a8f702a3f2008cb2908c2c5/jupyter_lab_utils_mrlynn-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "40d8b65c290faac631ed85c48b3a6c69877362b1ba074e6350810d3477bec468",
"md5": "623c9170babe2a4061dfa1f07b75cc14",
"sha256": "d758e68dc7e14bda66e2b784a6c17b211fac74a760955a066f34e89d95516f56"
},
"downloads": -1,
"filename": "jupyter_lab_utils_mrlynn-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "623c9170babe2a4061dfa1f07b75cc14",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19926,
"upload_time": "2025-07-10T11:33:48",
"upload_time_iso_8601": "2025-07-10T11:33:48.589907Z",
"url": "https://files.pythonhosted.org/packages/40/d8/b65c290faac631ed85c48b3a6c69877362b1ba074e6350810d3477bec468/jupyter_lab_utils_mrlynn-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 11:33:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mrlynn",
"github_project": "jupyter-lab-utils",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "jupyter-lab-utils-mrlynn"
}
JSON
