iotlabkit 1.0.0__py3-none-any.whl

iotlabkit/doctor.py

@@ -0,0 +1,160 @@
+"""System diagnostic tool for verifying Python environment, dependencies, and configuration.
+
+Ensures beginner students can pinpoint missing packages, tools, or configuration errors.
+Follows strict security practices: NEVER prints sensitive credential values.
+"""
+
+import os
+import platform
+import shutil
+import sys
+from typing import Dict, List, Tuple
+
+
+def check_python_version() -> Tuple[bool, str]:
+    """Verifies that the Python version is at least 3.9."""
+    major, minor, micro = sys.version_info[:3]
+    version_str = f"{major}.{minor}.{micro}"
+    if sys.version_info >= (3, 9):
+        return True, f"Python {version_str} ({sys.executable})"
+    return (
+        False,
+        f"Python {version_str} is below required minimum 3.9. Please upgrade to Python 3.10+.",
+    )
+
+
+def check_tool(binary_name: str) -> Tuple[bool, str]:
+    """Checks whether a system binary/executable is in PATH."""
+    path = shutil.which(binary_name)
+    if path:
+        return True, f"Found at {path}"
+    return False, "Not found in PATH (optional)"
+
+
+def check_python_package(package_name: str, import_name: str = None) -> Tuple[bool, str]:
+    """Checks whether a Python package is importable and retrieves its version."""
+    import_target = import_name or package_name
+    try:
+        mod = __import__(import_target)
+        version = getattr(mod, "__version__", "installed")
+        return True, f"v{version}"
+    except ImportError:
+        return False, "Not installed"
+
+
+def check_env_var_safe(var_name: str) -> Tuple[bool, str]:
+    """Safely checks if an environment variable is set without leaking secrets."""
+    val = os.environ.get(var_name)
+    if not val:
+        return False, "[Not Set]"
+    masked = f"[Configured: {len(val)} chars, ends with '...{val[-3:]}']" if len(val) >= 4 else "[Configured]"
+    return True, masked
+
+
+def run_doctor() -> int:
+    """Executes the full diagnostic suite and prints beginner-friendly reports."""
+    print("=" * 70)
+    print("                iotlabkit Doctor - Environment Diagnostics")
+    print("=" * 70)
+
+    all_passed = True
+
+    # 1. Python Environment
+    print("\n[1] Python Runtime:")
+    py_ok, py_msg = check_python_version()
+    status_icon = "✓" if py_ok else "✗"
+    print(f"  {status_icon} Python Version   : {py_msg}")
+    print(f"    Platform         : {platform.system()} {platform.release()} ({platform.machine()})")
+    if not py_ok:
+        all_passed = False
+
+    # 2. Command Line Tools
+    print("\n[2] System Binaries:")
+    tools = [
+        ("git", "Version control & repository cloning"),
+        ("curl", "HTTP request testing tool"),
+        ("mosquitto", "Eclipse Mosquitto local MQTT broker (Prog 9)"),
+        ("mosquitto_sub", "Mosquitto CLI subscriber tool"),
+    ]
+    for binary, desc in tools:
+        found, msg = check_tool(binary)
+        icon = "✓" if found else "!"
+        print(f"  {icon} {binary:<16}: {msg} - {desc}")
+
+    # 3. Layer Dependencies
+    print("\n[3] Python Packages by Layer:")
+
+    package_groups = {
+        "Core & Utilities": [
+            ("requests", "requests"),
+            ("python-dotenv", "dotenv"),
+            ("flask", "flask"),
+        ],
+        "IoT & Protocols": [
+            ("paho-mqtt", "paho.mqtt"),
+        ],
+        "Data Analytics": [
+            ("pandas", "pandas"),
+            ("matplotlib", "matplotlib"),
+        ],
+        "Machine Learning": [
+            ("scikit-learn", "sklearn"),
+            ("joblib", "joblib"),
+        ],
+        "Dashboards": [
+            ("streamlit", "streamlit"),
+        ],
+    }
+
+    missing_packages = []
+
+    for group_name, pkgs in package_groups.items():
+        print(f"  -- {group_name} --")
+        for pkg_name, imp_name in pkgs:
+            installed, ver_info = check_python_package(pkg_name, imp_name)
+            icon = "✓" if installed else "✗"
+            print(f"    {icon} {pkg_name:<16}: {ver_info}")
+            if not installed:
+                missing_packages.append(pkg_name)
+
+    # 4. Safe Cloud Configuration Check
+    print("\n[4] Cloud Credentials & Config (Safe Check - No Secrets Revealed):")
+    env_vars = [
+        ("SUPABASE_URL", "Supabase project URL (Prog 5, 6, 10)"),
+        ("SUPABASE_KEY", "Supabase anon/public API key (Prog 5, 6, 10)"),
+        ("FIREBASE_DATABASE_URL", "Firebase Realtime DB URL (Prog 5, 6, 10)"),
+        ("THINGSBOARD_ACCESS_TOKEN", "ThingsBoard Device Token (Prog 7)"),
+        ("THINGSBOARD_BROKER", "ThingsBoard Broker host (Prog 7)"),
+        ("MQTT_BROKER_HOST", "Custom MQTT broker host (Prog 6, 9)"),
+    ]
+    for var_name, desc in env_vars:
+        is_set, safe_info = check_env_var_safe(var_name)
+        icon = "✓" if is_set else "-"
+        print(f"  {icon} {var_name:<26}: {safe_info} ({desc})")
+
+    # 5. Diagnostic Summary
+    print("\n" + "=" * 70)
+    print("                          Summary & Recommendations")
+    print("=" * 70)
+    if missing_packages:
+        print(f"\n! Note: {len(missing_packages)} optional packages are currently uninstalled.")
+        print("  To install packages for specific practicals, you can run:")
+        print("    pip install iotlabkit[analytics]   # For Data Analytics practicals (11-14)")
+        print("    pip install iotlabkit[ml]          # For Machine Learning practicals (15-17)")
+        print("    pip install iotlabkit[iot]         # For Communication practicals (5-7, 9-10)")
+        print("    pip install iotlabkit[dashboard]   # For Streamlit dashboards")
+        print("    pip install iotlabkit[all]         # To install all dependencies at once")
+    else:
+        print("\n✓ All Python packages for all 13 practicals are installed and ready!")
+
+    print(
+        "\nReminder: Programs 8 (CoAP) runs with zero external packages (pure standard library).\n"
+        "Cloud credentials only need to be configured in generated `.env` files for Programs 5, 6, 7, and 10."
+    )
+    print("=" * 70)
+
+    return 0 if py_ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(run_doctor())

iotlabkit/generator.py

@@ -0,0 +1,110 @@
+"""Project generator for IoT Laboratory practicals.
+
+Generates self-contained, runnable practical directories with requirements.txt,
+README.md, .env.example, source files, and dataset loaders.
+Supports two execution modes:
+  - 'learning': Rich comments, step-by-step guides, architecture diagrams, viva Q&A.
+  - 'exam': Clean, concise, minimal comments, essential commands, viva Q&A.
+"""
+
+import os
+import sys
+from typing import Dict, List, Optional
+from iotlabkit.registry import get_program, ProgramInfo
+
+
+def prompt_overwrite_confirmation(directory: str) -> bool:
+    """Prompts the user before overwriting existing files in a directory."""
+    if not os.path.exists(directory):
+        return True
+    existing_files = os.listdir(directory)
+    if not existing_files:
+        return True
+
+    print(f"\n⚠️  Warning: Target directory '{directory}' already exists and contains {len(existing_files)} file(s):")
+    for f in existing_files[:5]:
+        print(f"   - {f}")
+    if len(existing_files) > 5:
+        print(f"   ... and {len(existing_files) - 5} more.")
+
+    try:
+        reply = input("\nDo you want to overwrite existing files? [y/N]: ").strip().lower()
+        return reply in ("y", "yes")
+    except (EOFError, KeyboardInterrupt):
+        return False
+
+
+def generate_program(
+    program_id: int,
+    output_dir: Optional[str] = None,
+    mode: str = "learning",
+    force: bool = False,
+    interactive: bool = True,
+) -> str:
+    """Generates a complete project directory for the requested practical.
+
+    Args:
+        program_id: Practical program number (5-17).
+        output_dir: Target directory path (defaults to 'labXX').
+        mode: Presentation mode ('learning' or 'exam').
+        force: If True, overwrites existing directory without prompt.
+        interactive: If True, prompts user before overwriting.
+
+    Returns:
+        The absolute path to the generated project directory.
+    """
+    prog_info: ProgramInfo = get_program(program_id)
+
+    valid_modes = ("learning", "exam")
+    clean_mode = mode.lower().strip()
+    if clean_mode not in valid_modes:
+        raise ValueError(
+            f"Invalid mode '{mode}'. Supported modes are: {', '.join(valid_modes)}"
+        )
+
+    target_dir = output_dir or f"lab{prog_info.code}"
+    target_abs = os.path.abspath(target_dir)
+
+    # Check for existing files
+    if not force and interactive:
+        if not prompt_overwrite_confirmation(target_dir):
+            print(f"Generation cancelled. Directory '{target_dir}' was preserved.")
+            return target_abs
+
+    os.makedirs(target_abs, exist_ok=True)
+
+    # Retrieve generator function from program template module
+    generator_fn = prog_info.get_generator()
+    files_to_write: Dict[str, str] = generator_fn(target_abs, clean_mode)
+
+    print(f"\n🚀 Generating Program {prog_info.id}: {prog_info.title}")
+    print(f"   Mode: {clean_mode.upper()}")
+    print(f"   Target Directory: {target_abs}\n")
+
+    for rel_path, content in files_to_write.items():
+        full_path = os.path.join(target_abs, rel_path)
+        parent_dir = os.path.dirname(full_path)
+        if parent_dir:
+            os.makedirs(parent_dir, exist_ok=True)
+
+        with open(full_path, "w", encoding="utf-8") as f:
+            f.write(content)
+        print(f"   ✓ Created: {rel_path}")
+
+    print("\n" + "=" * 70)
+    print(f"🎉 Project successfully generated in '{target_dir}'!")
+    print("=" * 70)
+    print("\nNext steps to run this practical:")
+    print(f"  1. Navigate to the project directory:")
+    print(f"     cd {target_dir}")
+    print(f"  2. Install dependencies (recommended in a virtual environment):")
+    print(f"     pip install -r requirements.txt")
+    if prog_info.requires_credentials:
+        print(f"  3. Configure environment variables:")
+        print(f"     cp .env.example .env")
+        print(f"     (Open .env in any editor and enter your credentials)")
+    print(f"  4. Follow instructions in '{target_dir}/README.md':")
+    print(f"     {prog_info.setup_steps[0] if prog_info.setup_steps else 'python main.py'}")
+    print("=" * 70 + "\n")
+
+    return target_abs