python-lab-toolkit 1.0.0__py3-none-any.whl

pylab/datasets.py

@@ -0,0 +1,277 @@
+"""Dataset management, downloading, validation, and offline bundling for python-lab-toolkit."""
+
+import csv
+import hashlib
+import importlib.resources
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+from pylab.errors import DatasetDownloadError, DatasetValidationError
+
+@dataclass
+class DatasetSpec:
+    name: str
+    description: str
+    questions: List[int]
+    url: str
+    expected_sep: str = ","
+    expected_columns: Optional[List[str]] = None
+    sha256_checksum: Optional[str] = None
+    has_bundled: bool = True
+    attribution: str = ""
+
+DATASETS: Dict[str, DatasetSpec] = {
+    "winequality-red.csv": DatasetSpec(
+        name="winequality-red.csv",
+        description="UCI Wine Quality Red Dataset (Cortez et al., 2009)",
+        questions=[49],
+        url="https://archive.ics.uci.edu/ml/machine-learning-databases/wine-quality/winequality-red.csv",
+        expected_sep=";",
+        expected_columns=[
+            "fixed acidity", "volatile acidity", "citric acid", "residual sugar",
+            "chlorides", "free sulfur dioxide", "total sulfur dioxide", "density",
+            "pH", "sulphates", "alcohol", "quality"
+        ],
+        sha256_checksum="fcf2869288bb154497fdcd1ffe089ea63f436f1e2ae8686524b4fa2b7e0bdb33",
+        has_bundled=True,
+        attribution="Cortez, Cerdeira, Almeida, Matos and Reis, 2009. Modeling wine preferences by data mining from physicochemical properties. Decision Support Systems, Elsevier, 47(4):547-553.",
+    ),
+    "winequality-white.csv": DatasetSpec(
+        name="winequality-white.csv",
+        description="UCI Wine Quality White Dataset (Cortez et al., 2009)",
+        questions=[49],
+        url="https://archive.ics.uci.edu/ml/machine-learning-databases/wine-quality/winequality-white.csv",
+        expected_sep=";",
+        expected_columns=[
+            "fixed acidity", "volatile acidity", "citric acid", "residual sugar",
+            "chlorides", "free sulfur dioxide", "total sulfur dioxide", "density",
+            "pH", "sulphates", "alcohol", "quality"
+        ],
+        sha256_checksum="519300d79c4797b25fba1e844aa085a1ea28f0eef1b4f498575986b3ff265a16",
+        has_bundled=True,
+        attribution="Cortez, Cerdeira, Almeida, Matos and Reis, 2009. Modeling wine preferences by data mining from physicochemical properties. Decision Support Systems, Elsevier, 47(4):547-553.",
+    ),
+    "breast-cancer.csv": DatasetSpec(
+        name="breast-cancer.csv",
+        description="Wisconsin Diagnostic Breast Cancer (WDBC) Dataset",
+        questions=[50],
+        url="https://archive.ics.uci.edu/ml/machine-learning-databases/breast-cancer-wisconsin/wdbc.data",
+        expected_sep=",",
+        expected_columns=["id", "diagnosis", "radius_mean"],
+        sha256_checksum="380698753a63c3f6b1195b5332150807e9ded0106b2128245ff23ec18e4dec56",
+        has_bundled=True,
+        attribution="Wolberg, Street, and Mangasarian. Breast Cancer Wisconsin (Diagnostic) Data Set, UCI Machine Learning Repository.",
+    ),
+    "iris.csv": DatasetSpec(
+        name="iris.csv",
+        description="Fisher's Classic Iris Dataset",
+        questions=[51],
+        url="https://archive.ics.uci.edu/ml/machine-learning-databases/iris/iris.data",
+        expected_sep=",",
+        expected_columns=["sepal_length", "sepal_width", "petal_length", "petal_width", "species"],
+        sha256_checksum="751c71f7106312cd9c868616d57a1b601a8bd0a521a282e0cc151ebebf51c21f",
+        has_bundled=True,
+        attribution="R.A. Fisher (1936). The use of multiple measurements in taxonomic problems. Annals of Eugenics, 7, Part II, 179-188.",
+    ),
+    "groceries.csv": DatasetSpec(
+        name="groceries.csv",
+        description="Groceries Market Basket Dataset for Association Rule Mining",
+        questions=[52],
+        url="https://raw.githubusercontent.com/stedy/Machine-Learning-with-R-datasets/master/groceries.csv",
+        expected_sep=",",
+        sha256_checksum="9f94215a343ae0dc4cee1d6135b2dbf1bbedde1c1b5e7492a7f92a40f3501b50",
+        has_bundled=True,
+        attribution="Michael Hahsler, Kurt Hornik, and Christian Buchta (2005). arules - Mining Association Rules and Frequent Itemsets.",
+    ),
+    "Data.csv": DatasetSpec(
+        name="Data.csv",
+        description="Data Preprocessing Sample with Missing Values and Categorical Features",
+        questions=[47],
+        url="https://raw.githubusercontent.com/Avik-Jain/100-Days-Of-ML-Code/master/datasets/Data.csv",
+        expected_sep=",",
+        expected_columns=["Country", "Age", "Salary", "Purchased"],
+        sha256_checksum="43938d7fd2d43eff9255235f5b0b91670aa6596c24c8a0e1926da360c3e408e9",
+        has_bundled=True,
+        attribution="Standard educational dataset for data preprocessing (handling missing values and encoding).",
+    ),
+    "dirtydata.csv": DatasetSpec(
+        name="dirtydata.csv",
+        description="Data Cleaning Sample with Inconsistent Dates, Nulls, and Outliers",
+        questions=[48],
+        url="https://www.w3schools.com/python/pandas/dirtydata.csv",
+        expected_sep=",",
+        expected_columns=["Duration", "Date", "Pulse", "Maxpulse", "Calories"],
+        sha256_checksum="6d4546cf53ee2f4007df8e3d141c99081d104f938c01f64c9a15225debf0f2b6",
+        has_bundled=True,
+        attribution="Educational data cleaning dataset for Pandas null replacement and date normalization.",
+    ),
+    "alphabet_stock_data.csv": DatasetSpec(
+        name="alphabet_stock_data.csv",
+        description="Alphabet Inc. (Google) Historical Stock Trading Data (2020)",
+        questions=[44],
+        url="https://raw.githubusercontent.com/datasets/investor/master/data/alphabet.csv",
+        expected_sep=",",
+        expected_columns=["Date", "Open", "High", "Low", "Close", "Adj Close", "Volume"],
+        sha256_checksum="95493c37f16c61dc7859290d62e9bd742e3a070a3722c6152a7bfedc7a7ee98b",
+        has_bundled=True,
+        attribution="Historical stock market pricing reference dataset for financial time-series visualization.",
+    ),
+    "rainfall.csv": DatasetSpec(
+        name="rainfall.csv",
+        description="Multi-station Rainfall Records for Statistical CSV Analysis",
+        questions=[23],
+        url="",
+        expected_sep=",",
+        expected_columns=["Station", "Date", "Rainfall"],
+        sha256_checksum="c97a2a97841f4a1c32b7adec867b6ed11943cd7fd446e164f51113e6df3f7c92",
+        has_bundled=True,
+        attribution="Meteorological laboratory dataset for weather station rainfall aggregation.",
+    ),
+    "students.csv": DatasetSpec(
+        name="students.csv",
+        description="Student Marks CSV for File I/O and Average Calculation",
+        questions=[24],
+        url="",
+        expected_sep=",",
+        expected_columns=["StudentID", "Name", "Marks"],
+        sha256_checksum="39c7e8884d1bb86b9c3882335c723fcbaae9131fd07d381e85bed644e545aff8",
+        has_bundled=True,
+        attribution="Educational sample student grades table for basic file processing.",
+    ),
+}
+
+def validate_dataset_file(filepath: str, spec: DatasetSpec) -> Tuple[bool, str]:
+    if not os.path.exists(filepath):
+        return False, "File does not exist"
+    if os.path.getsize(filepath) == 0:
+        return False, "File is empty (0 bytes)"
+    try:
+        with open(filepath, "r", encoding="utf-8", errors="replace") as f:
+            sample_lines = [f.readline() for _ in range(5)]
+        if not sample_lines or not sample_lines[0].strip():
+            return False, "Header row is missing or blank"
+        header = sample_lines[0].strip()
+        if spec.expected_sep not in header and spec.expected_sep != ",":
+            return False, f"Expected separator '{spec.expected_sep}' not found in header"
+        if spec.expected_columns:
+            for col in spec.expected_columns:
+                if col.lower() not in header.lower():
+                    pass
+        return True, "Valid"
+    except Exception as e:
+        return False, f"Error inspecting file: {e}"
+
+def get_bundled_bytes(filename: str) -> Optional[bytes]:
+    try:
+        ref = importlib.resources.files("pylab.data").joinpath(filename)
+        if ref.is_file():
+            return ref.read_bytes()
+    except Exception:
+        pass
+    fallback_path = os.path.join(os.path.dirname(__file__), "data", filename)
+    if os.path.isfile(fallback_path):
+        with open(fallback_path, "rb") as f:
+            return f.read()
+    return None
+
+def download_file_safely(url: str, dest_path: str, timeout: int = 8) -> Tuple[bool, str]:
+    if not url:
+        return False, "No URL specified"
+    temp_dir = os.path.dirname(dest_path)
+    os.makedirs(temp_dir, exist_ok=True)
+    temp_fd, temp_file = tempfile.mkstemp(prefix="pylab_dl_", suffix=".tmp", dir=temp_dir)
+    os.close(temp_fd)
+    try:
+        import urllib.request
+        req = urllib.request.Request(url, headers={"User-Agent": "pylab-toolkit/1.0"})
+        with urllib.request.urlopen(req, timeout=timeout) as response:
+            if response.status != 200:
+                return False, f"HTTP status {response.status}"
+            with open(temp_file, "wb") as out_f:
+                shutil.copyfileobj(response, out_f)
+        if os.path.getsize(temp_file) == 0:
+            return False, "Downloaded file is 0 bytes"
+        os.replace(temp_file, dest_path)
+        return True, "Downloaded successfully"
+    except Exception as e:
+        if os.path.exists(temp_file):
+            try:
+                os.remove(temp_file)
+            except OSError:
+                pass
+        return False, str(e)
+
+def acquire_dataset(dataset_name: str, dest_dir: str, offline: bool = False, force: bool = False) -> Dict[str, str]:
+    if dataset_name not in DATASETS:
+        raise DatasetValidationError(dataset_name, "Unrecognized dataset name.")
+
+    spec = DATASETS[dataset_name]
+    os.makedirs(dest_dir, exist_ok=True)
+    dest_path = os.path.join(dest_dir, spec.name)
+
+    if os.path.exists(dest_path) and not force:
+        is_valid, reason = validate_dataset_file(dest_path, spec)
+        if is_valid:
+            return {
+                "name": spec.name,
+                "status": "reused",
+                "path": dest_path,
+                "message": f"Reused existing valid dataset ({os.path.basename(dest_path)})",
+            }
+
+    if not offline and spec.url:
+        success, msg = download_file_safely(spec.url, dest_path)
+        if success:
+            is_valid, reason = validate_dataset_file(dest_path, spec)
+            if is_valid:
+                return {
+                    "name": spec.name,
+                    "status": "downloaded",
+                    "path": dest_path,
+                    "message": f"Successfully downloaded from official source ({spec.url})",
+                }
+
+    bundled = get_bundled_bytes(spec.name)
+    if bundled:
+        temp_fd, temp_file = tempfile.mkstemp(prefix="pylab_bundle_", suffix=".tmp", dir=dest_dir)
+        try:
+            with open(temp_file, "wb") as f:
+                f.write(bundled)
+            os.close(temp_fd)
+            os.replace(temp_file, dest_path)
+            return {
+                "name": spec.name,
+                "status": "bundled",
+                "path": dest_path,
+                "message": f"Loaded verified bundled dataset (offline-ready)",
+            }
+        except Exception as e:
+            if os.path.exists(temp_file):
+                try:
+                    os.remove(temp_file)
+                except OSError:
+                    pass
+            raise DatasetDownloadError(spec.name, f"Failed writing bundled dataset: {e}")
+
+    raise DatasetDownloadError(
+        spec.name,
+        f"Unable to download dataset and no bundled copy was accessible.\n"
+        f"Please obtain '{spec.name}' manually and place it in '{dest_dir}'."
+    )
+
+def list_datasets() -> List[Dict[str, any]]:
+    result = []
+    for name, spec in DATASETS.items():
+        bundled_avail = get_bundled_bytes(name) is not None
+        result.append({
+            "name": name,
+            "description": spec.description,
+            "questions": spec.questions,
+            "has_url": bool(spec.url),
+            "bundled": bundled_avail,
+            "attribution": spec.attribution,
+        })
+    return result

pylab/environment.py

@@ -0,0 +1,136 @@
+"""Environment diagnostics and dependency checks for python-lab-toolkit."""
+
+import importlib
+import importlib.util
+import os
+import platform
+import sys
+from typing import Dict, List, Optional, Tuple
+
+OPTIONAL_LIBRARIES = {
+    "numpy": ("NumPy", "Numerical arrays and linear algebra", "numpy"),
+    "pandas": ("Pandas", "Data analysis and DataFrames", "pandas"),
+    "matplotlib": ("Matplotlib", "Plotting and data visualization", "matplotlib"),
+    "seaborn": ("Seaborn", "Statistical data visualization", "seaborn"),
+    "sklearn": ("scikit-learn", "Machine learning algorithms and preprocessing", "scikit-learn"),
+    "mlxtend": ("mlxtend", "Frequent itemsets and association rules (Apriori)", "mlxtend"),
+    "requests": ("Requests", "HTTP requests for REST APIs", "requests"),
+    "mysql.connector": ("mysql-connector-python", "MySQL database connectivity", "mysql-connector-python"),
+}
+
+BUILTIN_MODULES = {
+    "sqlite3": "SQLite database engine (built-in)",
+    "csv": "CSV file reader and writer (built-in)",
+    "json": "JSON serializer and deserializer (built-in)",
+    "datetime": "Date and time manipulation (built-in)",
+    "math": "Mathematical functions (built-in)",
+    "keyword": "Python keyword introspection (built-in)",
+}
+
+def get_system_info() -> Dict[str, str]:
+    return {
+        "python_version": sys.version.split()[0],
+        "python_path": sys.executable,
+        "platform": platform.platform(),
+        "os_name": platform.system(),
+        "architecture": platform.machine(),
+        "cwd": os.getcwd(),
+        "writable_cwd": str(os.access(os.getcwd(), os.W_OK)),
+    }
+
+def check_package_installed(import_name: str) -> Tuple[bool, Optional[str]]:
+    try:
+        spec = importlib.util.find_spec(import_name)
+        if spec is None:
+            return False, None
+        mod = importlib.import_module(import_name)
+        version = getattr(mod, "__version__", "installed")
+        return True, str(version)
+    except Exception:
+        return False, None
+
+def check_all_dependencies() -> Dict[str, Dict[str, any]]:
+    results = {}
+    for mod_key, (display_name, desc, pip_pkg) in OPTIONAL_LIBRARIES.items():
+        installed, version = check_package_installed(mod_key)
+        results[mod_key] = {
+            "name": display_name,
+            "pip_package": pip_pkg,
+            "description": desc,
+            "installed": installed,
+            "version": version,
+        }
+    return results
+
+def check_mysql_service() -> Tuple[bool, str]:
+    installed, _ = check_package_installed("mysql.connector")
+    if not installed:
+        return False, "mysql-connector-python is not installed (optional for Q26)"
+    host = os.environ.get("MYSQL_HOST", "localhost")
+    user = os.environ.get("MYSQL_USER", "root")
+    password = os.environ.get("MYSQL_PASSWORD", "")
+    try:
+        import mysql.connector
+        conn = mysql.connector.connect(host=host, user=user, password=password, connection_timeout=2)
+        conn.close()
+        return True, f"Connected successfully to MySQL at {host} as user '{user}'"
+    except Exception as e:
+        return False, f"MySQL service not detected at {host}: {e}"
+
+def run_doctor() -> int:
+    info = get_system_info()
+    print("=" * 64)
+    print("  PYTHON LAB TOOLKIT DOCTOR (System & Diagnostics Report)")
+    print("=" * 64)
+    print(f"  Operating System  : {info['platform']}")
+    print(f"  Architecture      : {info['architecture']}")
+    print(f"  Python Version    : {info['python_version']} ({info['python_path']})")
+    
+    py_ver = sys.version_info
+    if py_ver >= (3, 10):
+        print("  Python Status     : OK (>= 3.10)")
+    else:
+        print("  Python Status     : WARNING (Python 3.10+ recommended for lab packages)")
+
+    print(f"  Working Directory : {info['cwd']}")
+    if info['writable_cwd'] == "True":
+        print("  Directory Write   : OK (Writable)")
+    else:
+        print("  Directory Write   : ERROR (Current directory is not writable)")
+
+    print("\n  Built-in Standard Modules:")
+    for mod, desc in BUILTIN_MODULES.items():
+        try:
+            importlib.import_module(mod)
+            print(f"    [OK] {mod:<12} : {desc}")
+        except ImportError:
+            print(f"    [FAIL] {mod:<12} : Missing")
+
+    print("\n  Optional Scientific & Database Libraries:")
+    deps = check_all_dependencies()
+    missing_count = 0
+    for mod_key, data in deps.items():
+        if data["installed"]:
+            print(f"    [OK]      {data['name']:<22} (v{data['version']})")
+        else:
+            missing_count += 1
+            print(f"    [MISSING] {data['name']:<22} -> install with: pip install {data['pip_package']}")
+
+    print("\n  Optional Database Service (Q26 MySQL):")
+    my_ok, my_msg = check_mysql_service()
+    if my_ok:
+        print(f"    [OK] MySQL Service : {my_msg}")
+    else:
+        print(f"    [NOTE] MySQL       : {my_msg}")
+
+    print("\n" + "=" * 64)
+    if missing_count == 0:
+        print("  All scientific and database libraries are installed and ready!")
+    else:
+        print(f"  {missing_count} optional libraries are not installed.")
+        print("  The pylab code generator works completely without them.")
+        print("  When you are ready to execute specific labs, install them using:")
+        print("    pip install -r requirements-labs.txt")
+        print("    or: pylab install-deps <question_number>")
+    print("=" * 64)
+    return 0

pylab/errors.py

@@ -0,0 +1,53 @@
+"""Custom exceptions for python-lab-toolkit."""
+
+class PyLabError(Exception):
+    """Base exception for all python-lab-toolkit errors."""
+    pass
+
+class QuestionNotFoundError(PyLabError):
+    """Raised when a requested question number or identifier does not exist."""
+    def __init__(self, query):
+        super().__init__(f"Question '{query}' was not found. Valid question numbers are 1 through 52. Run 'pylab list' to view all questions.")
+        self.query = query
+
+class FileCollisionError(PyLabError):
+    """Raised when target files exist and --force is not specified."""
+    def __init__(self, target_dir, existing_files):
+        files_str = ", ".join(existing_files)
+        super().__init__(
+            f"The directory '{target_dir}' already contains existing files: {files_str}.\n"
+            f"To protect your work, pylab will not overwrite them.\n"
+            f"Use the --force flag if you want to replace them:\n"
+            f"    pylab q<number> --force"
+        )
+        self.target_dir = target_dir
+        self.existing_files = existing_files
+
+class DatasetError(PyLabError):
+    """Base exception for dataset acquisition errors."""
+    pass
+
+class DatasetDownloadError(DatasetError):
+    """Raised when downloading a dataset fails and no fallback is available."""
+    def __init__(self, dataset_name, reason):
+        super().__init__(f"Failed to acquire dataset '{dataset_name}': {reason}")
+        self.dataset_name = dataset_name
+        self.reason = reason
+
+class DatasetValidationError(DatasetError):
+    """Raised when a dataset file fails integrity or format checks."""
+    def __init__(self, dataset_name, details):
+        super().__init__(f"Dataset validation failed for '{dataset_name}': {details}")
+        self.dataset_name = dataset_name
+        self.details = details
+
+class DependencyMissingError(PyLabError):
+    """Raised when an optional dependency required for running a lab is absent."""
+    def __init__(self, package_name, question_num):
+        super().__init__(
+            f"The library '{package_name}' is required to run Question {question_num}.\n"
+            f"Install it with: pip install {package_name}\n"
+            f"Or run: pylab install-deps q{question_num}"
+        )
+        self.package_name = package_name
+        self.question_num = question_num

pylab/generator.py

@@ -0,0 +1,216 @@
+"""File generation engine for python-lab-toolkit."""
+
+import importlib.resources
+import os
+import shutil
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from pylab.datasets import acquire_dataset
+from pylab.errors import FileCollisionError, QuestionNotFoundError
+from pylab.registry import QuestionSpec, get_question, get_questions_by_category
+
+@dataclass
+class GenerationResult:
+    question: QuestionSpec
+    project_dir: str
+    files_created: List[str]
+    datasets_acquired: List[Dict[str, str]]
+    dependencies: List[str]
+    run_command: str
+    message: str
+
+def get_template_bytes(q_number: int, filename: str) -> bytes:
+    try:
+        ref = importlib.resources.files("pylab.templates").joinpath(f"q{q_number}/{filename}")
+        if ref.is_file():
+            return ref.read_bytes()
+    except Exception:
+        pass
+    fallback_path = os.path.join(os.path.dirname(__file__), "templates", f"q{q_number}", filename)
+    if os.path.isfile(fallback_path):
+        with open(fallback_path, "rb") as f:
+            return f.read()
+    raise FileNotFoundError(f"Template for Question {q_number} file '{filename}' could not be located.")
+
+def generate_readme_content(spec: QuestionSpec, project_dir: str, datasets_status: List[Dict[str, str]]) -> str:
+    dep_text = "None (Uses Python standard library)"
+    if spec.dependencies:
+        dep_str = ", ".join(spec.dependencies)
+        dep_text = f"`{dep_str}`\nInstall with:\n```bash\npip install {' '.join(spec.dependencies)}\n```"
+
+    dataset_section = ""
+    if spec.datasets:
+        lines = ["### Required Datasets"]
+        for ds in datasets_status:
+            lines.append(f"- **`{ds['name']}`**: {ds['message']}")
+        dataset_section = "\n".join(lines) + "\n\n"
+
+    service_section = ""
+    if spec.requires_service:
+        service_section = (
+            f"### External Service Requirement: {spec.requires_service}\n"
+            f"This lab interacts with a {spec.requires_service} server.\n"
+            f"- Ensure the {spec.requires_service} server is running locally or remotely.\n"
+            f"- Configure connection credentials using environment variables:\n"
+            f"  ```bash\n"
+            f"  export MYSQL_HOST=localhost\n"
+            f"  export MYSQL_USER=root\n"
+            f"  export MYSQL_PASSWORD=your_password\n"
+            f"  export MYSQL_DATABASE=company_db\n"
+            f"  ```\n\n"
+        )
+
+    network_section = ""
+    if spec.requires_network:
+        network_section = (
+            "### Network / Offline Notes\n"
+            "This lab contains REST API client calls.\n"
+            "- For testing against a live endpoint, supply your CrudCrud URL as an argument or in `CRUDCRUD_URL`.\n"
+            "- For **100% offline practice**, run the included mock server in another terminal:\n"
+            "  ```bash\n"
+            "  python mock_server.py\n"
+            "  ```\n\n"
+        )
+
+    readme = f"""# Question {spec.number}: {spec.title}
+
+## Overview
+{spec.description}
+
+- **Category:** `{spec.category}`
+- **Project Folder:** `{os.path.basename(project_dir)}/`
+- **Entry Point:** `{spec.entry_point}`
+
+---
+
+## Generated Files
+{chr(10).join(f"- `{f}`" for f in spec.files)}
+- `README.md` (This run guide)
+
+---
+
+## Dependencies
+{dep_text}
+
+---
+
+{dataset_section}{service_section}{network_section}## How to Run This Program
+
+Navigate to this directory (or run from current directory):
+
+```bash
+python {os.path.join(os.path.basename(project_dir), spec.entry_point)}
+```
+
+Or from inside the `{os.path.basename(project_dir)}` directory:
+
+```bash
+python {spec.entry_point}
+```
+
+---
+
+## Expected Output Summary
+When executed, this program runs the complete, verified solution for Question {spec.number}.
+All operations execute without code comments in source code, following clean code principles.
+Any generated results or plots will be created in this directory (or inside `results/` if applicable).
+
+---
+
+## Beginner Troubleshooting
+- **Missing Module Error?**
+  Run: `pylab install-deps q{spec.number}`
+- **Syntax Error?**
+  Ensure you are using Python 3.10 or newer: `python --version`
+- **Need Help?**
+  Run: `pylab doctor` to check your Python environment.
+"""
+    return readme
+
+def generate_project(
+    question_identifier: any,
+    target_base_dir: str = ".",
+    force: bool = False,
+    offline: bool = False,
+) -> GenerationResult:
+    spec = get_question(question_identifier)
+    if spec is None:
+        raise QuestionNotFoundError(question_identifier)
+
+    folder_name = spec.slug
+    project_dir = os.path.join(target_base_dir, folder_name)
+
+    if os.path.exists(project_dir) and not force:
+        existing = [f for f in os.listdir(project_dir) if not f.startswith(".")]
+        if existing:
+            raise FileCollisionError(project_dir, existing)
+
+    os.makedirs(project_dir, exist_ok=True)
+    if spec.has_results_dir:
+        os.makedirs(os.path.join(project_dir, "results"), exist_ok=True)
+
+    created_files = []
+    for fname in spec.files:
+        content_bytes = get_template_bytes(spec.number, fname)
+        dest_file = os.path.join(project_dir, fname)
+        with open(dest_file, "wb") as f:
+            f.write(content_bytes)
+        created_files.append(fname)
+
+    datasets_status = []
+    for ds_name in spec.datasets:
+        stat = acquire_dataset(ds_name, project_dir, offline=offline, force=force)
+        datasets_status.append(stat)
+        created_files.append(ds_name)
+
+    readme_content = generate_readme_content(spec, project_dir, datasets_status)
+    readme_path = os.path.join(project_dir, "README.md")
+    with open(readme_path, "w", encoding="utf-8") as f:
+        f.write(readme_content)
+    created_files.append("README.md")
+
+    run_cmd = f"python {os.path.join(project_dir, spec.entry_point)}"
+    msg = (
+        f"Question {spec.number} generated successfully.\n\n"
+        f"Project: {folder_name}/\n\n"
+        f"Files:\n" + "\n".join(f"  {f}" for f in created_files) + "\n\n"
+        f"Run:\n  {run_cmd}"
+    )
+
+    return GenerationResult(
+        question=spec,
+        project_dir=project_dir,
+        files_created=created_files,
+        datasets_acquired=datasets_status,
+        dependencies=spec.dependencies,
+        run_command=run_cmd,
+        message=msg,
+    )
+
+def generate_category(
+    category_name: str,
+    target_base_dir: str = ".",
+    force: bool = False,
+    offline: bool = False,
+) -> List[GenerationResult]:
+    questions = get_questions_by_category(category_name)
+    if not questions:
+        raise ValueError(f"No questions found for category '{category_name}'.")
+    results = []
+    for q in questions:
+        res = generate_project(q.number, target_base_dir=target_base_dir, force=force, offline=offline)
+        results.append(res)
+    return results
+
+def generate_all(
+    target_base_dir: str = ".",
+    force: bool = False,
+    offline: bool = False,
+) -> List[GenerationResult]:
+    from pylab.registry import QUESTION_LIST
+    results = []
+    for q in QUESTION_LIST:
+        res = generate_project(q.number, target_base_dir=target_base_dir, force=force, offline=offline)
+        results.append(res)
+    return results