Metadata-Version: 2.1
Name: python-lab-toolkit
Version: 1.0.0
Summary: A beginner-friendly CLI and toolkit to generate 52 complete Python lab solutions with automated dataset management.
Author-email: Python Lab Toolkit Developers <dev@pylabtoolkit.org>
License: MIT
Project-URL: Homepage, https://github.com/pylabtoolkit/python-lab-toolkit
Project-URL: Documentation, https://github.com/pylabtoolkit/python-lab-toolkit#readme
Project-URL: Repository, https://github.com/pylabtoolkit/python-lab-toolkit.git
Project-URL: Issues, https://github.com/pylabtoolkit/python-lab-toolkit/issues
Keywords: education,python-lab,code-generator,data-science,cli
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Provides-Extra: requests
Requires-Dist: requests>=2.25.0; extra == "requests"
Provides-Extra: labs
Requires-Dist: requests>=2.25.0; extra == "labs"
Requires-Dist: numpy>=1.20.0; extra == "labs"
Requires-Dist: pandas>=1.3.0; extra == "labs"
Requires-Dist: matplotlib>=3.4.0; extra == "labs"
Requires-Dist: seaborn>=0.11.0; extra == "labs"
Requires-Dist: scikit-learn>=1.0.0; extra == "labs"
Requires-Dist: mlxtend>=0.19.0; extra == "labs"
Requires-Dist: mysql-connector-python>=8.0.0; extra == "labs"

# Python Lab Toolkit (`python-lab-toolkit`)

[![PyPI Version](https://img.shields.io/badge/pypi-v1.0.0-blue.svg)](https://pypi.org/project/python-lab-toolkit/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Zero Comments in Generated Code](https://img.shields.io/badge/clean%20code-zero%20comments-brightgreen.svg)]()
[![Offline Ready](https://img.shields.io/badge/offline-bundled%20datasets-success.svg)]()

A beginner-friendly, production-quality Python package and CLI named `pylab` designed to generate complete, working, runnable solutions for all **52 Python laboratory questions** with automatic dataset downloading and verified offline support.

---

## Table of Contents
1. [Key Features](#key-features)
2. [Installation](#installation)
3. [Quick Start](#quick-start)
4. [Complete Command Reference](#complete-command-reference)
5. [The 52 Lab Questions Catalog](#the-52-lab-questions-catalog)
6. [Automated Dataset Management](#automated-dataset-management)
7. [Offline Installation & Laboratory Bundle](#offline-installation--laboratory-bundle)
8. [Database Configuration (SQLite & MySQL)](#database-configuration-sqlite--mysql)
9. [CGI Web Handlers and Local Test Servers](#cgi-web-handlers-and-local-test-servers)
10. [Troubleshooting & FAQ](#troubleshooting--faq)
11. [Development & Automated Testing](#development--automated-testing)
12. [PyPI Publication Guide](#pypi-publication-guide)
13. [License & Dataset Attribution](#license--dataset-attribution)

---

## 1. Key Features

- **Short, Intuitive Commands**: Generate any project with simple commands like `pylab q1`, `pylab q12`, `pylab q49`.
- **Zero Comments in Generated Code**: In accordance with clean code standards, generated Python source code contains **no explanatory inline comments, decorative comments, or header comments**, remaining self-explanatory through readable structure and expressive naming.
- **Real, Runnable Python Files**: Generates real files on disk (not hidden functions or stubs) that students and instructors can inspect, run, and modify.
- **Automated Dataset Handling**: Automatically downloads datasets when missing or instantly extracts verified bundled datasets when offline.
- **100% Offline Capable**: Small verified copies of all required datasets (`winequality-red.csv`, `iris.csv`, `breast-cancer.csv`, `groceries.csv`, `Data.csv`, `dirtydata.csv`, `alphabet_stock_data.csv`, `rainfall.csv`, `students.csv`) are bundled inside the package wheel.
- **Zero External Dependencies for Generator**: The `pylab` CLI and generator depend strictly on the Python standard library. It installs anywhere instantly without dependency conflicts.
- **Accidental Overwrite Protection**: Existing user files are never silently overwritten. Use `--force` to deliberately replace files.
- **Built-in System Doctor**: Run `pylab doctor` to check Python versions, directory permissions, and optional scientific libraries.

---

## 2. Installation

### Standard Installation via pip
```bash
python -m pip install python-lab-toolkit
```

### Optional Scientific Libraries
The core toolkit runs anywhere on standard Python. If you want to execute machine learning, plotting, or numerical labs (Q23, Q31-Q52), install the scientific packages:
```bash
python -m pip install -r requirements-labs.txt
```
Or install specific dependencies per question:
```bash
pylab install-deps q49
```

---

## 3. Quick Start

### 1. View Available Questions
```bash
pylab list
```

### 2. Generate a Single Question
Generate the modular text analysis lab (Question 12):
```bash
pylab q12
```
Output:
```text
Question 12 generated successfully.

Project: q12_text_analysis/

Files:
  text_preprocessor.py
  text_analyzer.py
  main_analyzer.py
  README.md

Run:
  python q12_text_analysis/main_analyzer.py
```

### 3. Run the Generated Program
```bash
python q12_text_analysis/main_analyzer.py
```

### 4. Generate Machine Learning Labs with Automatic Datasets
Generate the 22-step Wine Quality regression pipeline:
```bash
pylab q49
```
This automatically obtains `winequality-red.csv` and `winequality-white.csv`, creates `results/`, and generates `wine_regression.py` and `README.md`.

---

## 4. Complete Command Reference

| Command | Description |
| :--- | :--- |
| `pylab list` | Display all 52 registered questions with numbers, titles, and categories. |
| `pylab list --category <cat>` | Filter questions by category (`fundamentals`, `oop`, `pandas`, etc.). |
| `pylab q<N>` | Generate Question `<N>` (e.g. `pylab q1`, `pylab q25`, `pylab q49`). |
| `pylab q<N> --force` | Overwrite existing project files. |
| `pylab q<N> --offline` | Force usage of bundled offline datasets. |
| `pylab q<N> --output-dir <dir>` | Generate the project inside a specified directory. |
| `pylab category <cat>` | Generate all questions belonging to a specific category. |
| `pylab all` | Generate all 52 questions (prompts for confirmation). |
| `pylab all --yes` | Generate all 52 questions non-interactively. |
| `pylab doctor` | Inspect environment, Python version, directory write permissions, and libraries. |
| `pylab datasets` | Display status and metadata for all bundled and downloadable datasets. |
| `pylab install-deps <q>` | Check and install missing optional pip packages for a specific question. |
| `pylab version` | Show the installed toolkit version. |
| `pylab --help` | Display CLI help and options. |

---

## 5. The 52 Lab Questions Catalog

### Python Fundamentals (Questions 1–11)
- **Q1 (`q01_variable_name_validator`)**: Validate identifier rules and check reserved keywords using `keyword.iskeyword()`.
- **Q2 (`q02_single_number`)**: Find the unique integer in an array where all other integers appear twice using XOR ($O(n)$ time, $O(1)$ space).
- **Q3 (`q03_string_operations`)**: Implement `process_string()` to display uppercase, lowercase, length, slicing reversal `[::-1]`, and palindrome status.
- **Q4 (`q04_menu_string_processor`)**: Menu-driven program for substring checking, character occurrence counting, substring replacement, and uppercase conversion.
- **Q5 (`q05_phonebook`)**: Dictionary-based contact management supporting Add, Update, Search, Delete, and Display.
- **Q6 (`q06_simple_calculator`)**: Arithmetic calculator supporting `+`, `-`, `*`, `/`, `//`, `%`, `**` with zero-division handling.
- **Q7 (`q07_session_attendees`)**: Set operations on conference attendees: Union, Intersection, AI-only, and Cybersecurity-only.
- **Q8 (`q08_number_properties`)**: Functions verifying Even/Odd, Palindrome, Armstrong numbers, Prime numbers, and Perfect numbers.
- **Q9 (`q09_greet_people`)**: Variable argument function `greet_people(*names)` handling zero, one, or multiple parameters.
- **Q10 (`q10_password_strength`)**: Password validator testing length, digits, uppercase, lowercase, and special characters with detailed deficiency reporting.
- **Q11 (`q11_recursion`)**: Recursive sum and recursive factorial evaluated on $n = 5, 10, 18$.

### Modular Programming (Question 12)
- **Q12 (`q12_text_analysis`)**: Multi-module architecture with `text_preprocessor.py`, `text_analyzer.py`, and `main_analyzer.py` displaying required function docstrings via `__doc__`.

### Object-Oriented Programming (Questions 13–18)
- **Q13 (`q13_student_class`)**: `Student` class with `name`, `roll_number`, `course`, and `display()`.
- **Q14 (`q14_circle_class`)**: `Circle` class with radius, `area()`, and `circumference()` methods using `math.pi`.
- **Q15 (`q15_employee_salary`)**: `Employee` gross salary calculator with basic pay, HRA (20%), and DA (10%).
- **Q16 (`q16_smart_calculator`)**: `SmartCalculator` demonstrating default arguments, `*args` multiplication, and polymorphic type dispatch.
- **Q17 (`q17_complex_number`)**: `ComplexNumber` class with `+` (`__add__`) and `==` (`__eq__`) operator overloading.
- **Q18 (`q18_vehicle_inheritance`)**: `Vehicle` base class and `Car` derived class with method overriding and `super()`.

### Files, Exceptions, and Dates (Questions 19–22)
- **Q19 (`q19_file_word_counter`)**: Read text file, count lines, words, characters, find top 5 frequent words, and handle file exceptions. Includes `sample.txt`.
- **Q20 (`q20_custom_exception_age`)**: Custom exception `InvalidAgeException` validating ages between 18 and 60.
- **Q21 (`q21_transaction_handling`)**: Robust banking transaction demonstrating `try`, `except`, `else`, and `finally` blocks.
- **Q22 (`q22_date_formatter`)**: Date parser converting `dd-mm-yyyy` to `MonthName dd, yyyy` with invalid calendar date detection.

### CSV Processing (Questions 23–24)
- **Q23 (`q23_rainfall_analysis`)**: Read rainfall CSV data, calculate station averages, maximum rainfall record, standard deviation, and export results.
- **Q24 (`q24_students_csv`)**: Manage `students.csv`, find highest-scoring student, and compute class average marks.

### Database Systems (Questions 25–26)
- **Q25 (`q25_sqlite_library`)**: SQLite Library Management system with parameterized single inserts, `executemany()` batch inserts, category queries, and menu CLI.
- **Q26 (`q26_mysql_employee`)**: MySQL Employee Management system with parameterized queries, salary filtering (> ₹50,000), and secure environment credentials.

### REST API & Networking (Question 27)
- **Q27 (`q27_crudcrud_api`)**: Functional `requests`-based REST client performing Create, Read, Update, and Delete on students. Includes built-in `mock_server.py` for offline testing!

### CGI & Web Applications (Questions 28–30)
- **Q28 (`q28_cgi_login`)**: HTML login form and Python CGI handler displaying welcome response, with built-in `server.py`.
- **Q29 (`q29_cgi_registration`)**: MSc registration form and Python CGI script returning formatted admission receipt.
- **Q30 (`q30_cgi_crud`)**: Web-based database CRUD portal backed by SQLite, HTML frontend, and Python CGI HTTP server.

### NumPy and Pandas Numerical Analysis (Questions 31–43)
- **Q31 (`q31_numpy_matrix_operations`)**: Array 1–20 reshaped to 4×5, transpose, total/row/column sums, and even number extraction.
- **Q32 (`q32_numpy_slicing_reversal`)**: 5×5 array (1–25) submatrix slicing, row slicing, column slicing, and axis reversals.
- **Q33 (`q33_pandas_student_pass_fail`)**: Convert student marks Series to DataFrame, classify Pass/Fail, and filter passing students.
- **Q34 (`q34_pandas_employee_salary`)**: Departmental salary analysis computing average salary per department and top earner.
- **Q35 (`q35_pandas_sales_barchart`)**: 6 months sales table for 3 products, detecting top month, and plotting bar chart to `results/`.
- **Q36 (`q36_pandas_weather_plot`)**: 7-day weather table calculating average temperature and total rainfall, plotting temperature trend line.
- **Q37 (`q37_pandas_age_categorization`)**: Continuous age categorization using `pd.cut()` with mismatch detection.
- **Q38 (`q38_pandas_concat_rows`)**: Concatenate two student DataFrames along rows (`axis=0`).
- **Q39 (`q39_pandas_concat_cols`)**: Combine student DataFrames along columns (`axis=1`).
- **Q40 (`q40_pandas_concat_merge`)**: Concatenate student batches and merge with exam scores DataFrame on `student_id`.
- **Q41 (`q41_pandas_join_operations`)**: Relational join operations: Inner, Left, Right, and Outer joins with detailed semantics explanation.
- **Q42 (`q42_pandas_groupby_school`)**: Group school records by school code, compute mean/min/max age, and inspect GroupBy object type.
- **Q43 (`q43_pandas_groupby_multi`)**: Multi-column GroupBy (`['school_code', 'class']`) computing group counts with `size()`.

### Visualization and Preprocessing (Questions 44–48)
- **Q44 (`q44_alphabet_stock_visualization`)**: Alphabet stock historical data filtering, line plots, volume bar plot, stacked OHLC histogram, and scatter correlation.
- **Q45 (`q45_multi_plot_demonstration`)**: 2×2 multi-plot demonstration grid (waveform, categories, scatter, histogram).
- **Q46 (`q46_dataframe_barchart`)**: Grouped categorical bar plot with value annotations and legends.
- **Q47 (`q47_data_preprocessing`)**: Impute missing numerical values (`SimpleImputer`), One-Hot encode categorical features, and standard scale features (`StandardScaler`).
- **Q48 (`q48_dirtydata_cleaning`)**: Clean dirty dataset: fix inconsistent date formats, impute null calories, correct outlier duration, and drop duplicates.

### Machine Learning & Data Mining Pipelines (Questions 49–52)
- **Q49 (`q49_wine_quality_regression`)**: Full 22-step regression pipeline on red and white wine: data integration, correlation heatmap, feature scaling, Linear Regression, Decision Tree Regressor, Random Forest Regressor, and $R^2$, MAE, MSE, RMSE evaluation.
- **Q50 (`q50_breast_cancer_classification`)**: Breast cancer diagnosis classification, Random Forest feature ranking, top-feature reduction, and classifier comparison (Decision Tree, Random Forest, Logistic Regression) with confusion matrices and false-negative analysis.
- **Q51 (`q51_iris_clustering`)**: Unsupervised clustering on Iris features: standardization, K-Means ($k = 2, 3, 4$), elbow method, and 2D PCA cluster visualization.
- **Q52 (`q52_apriori_association_rules`)**: Market basket transaction processing with Apriori, frequent itemset generation, and association rules sorted by lift.

---

## 6. Automated Dataset Management

When generating questions requiring datasets, `pylab` automatically acquires them:

```text
q49_wine_quality_regression/
├── wine_regression.py
├── winequality-red.csv          <-- Auto-acquired
├── winequality-white.csv        <-- Auto-acquired
├── README.md
└── results/
```

### Dataset Registry
| Dataset Filename | Used In | Official Source | Bundled Offline |
| :--- | :--- | :--- | :--- |
| `winequality-red.csv` | Q49 | UCI Machine Learning Repository | Yes |
| `winequality-white.csv` | Q49 | UCI Machine Learning Repository | Yes |
| `breast-cancer.csv` | Q50 | UCI Machine Learning Repository | Yes |
| `iris.csv` | Q51 | UCI Machine Learning Repository | Yes |
| `groceries.csv` | Q52 | Association Mining Market Baskets | Yes |
| `Data.csv` | Q47 | ML Preprocessing Reference Data | Yes |
| `dirtydata.csv` | Q48 | Data Cleaning Reference Data | Yes |
| `alphabet_stock_data.csv` | Q44 | Financial Time Series Reference | Yes |
| `rainfall.csv` | Q23 | Weather Station Records | Yes |
| `students.csv` | Q24 | Student Grades Records | Yes |

To view dataset status at any time, run:
```bash
pylab datasets
```

---

## 7. Offline Installation & Laboratory Bundle

In lab environments where internet access is unavailable or restricted, you can prepare an offline installation bundle.

### Step 1: Prepare the Offline Wheels Folder (on an internet-connected machine)
```bash
mkdir -p offline_bundle/wheels
python -m pip download -d offline_bundle/wheels python-lab-toolkit
python -m pip download -d offline_bundle/wheels -r requirements-labs.txt
```

### Step 2: Install Completely Offline in the Laboratory
Transfer the `offline_bundle` folder to your offline laboratory computers and install:
```bash
python -m pip install --no-index --find-links ./offline_bundle/wheels python-lab-toolkit
```

### Step 3: Run Generation Offline
```bash
pylab q49 --offline
```
The toolkit will immediately use the verified bundled datasets stored inside the package wheel.

---

## 8. Database Configuration (SQLite & MySQL)

### SQLite (Q25 & Q30)
SQLite is built into Python. No installation, server configuration, or credentials are required. The database files (`library.db` and `cgi_records.db`) are created automatically in the project folder.

### MySQL (Q26)
Question 26 integrates with a MySQL database.
To run Question 26 against your MySQL server:
1. Start your local MySQL service (e.g. `sudo systemctl start mysqld` or through XAMPP / MySQL Workbench).
2. Configure credentials using environment variables:
   ```bash
   export MYSQL_HOST="localhost"
   export MYSQL_USER="root"
   export MYSQL_PASSWORD="your_password"
   export MYSQL_DATABASE="company_db"
   ```
3. Run the manager:
   ```bash
   python q26_mysql_employee/mysql_employee_manager.py
   ```
   Or run the automated demonstration:
   ```bash
   python q26_mysql_employee/mysql_employee_manager.py --demo
   ```

---

## 9. CGI Web Handlers and Local Test Servers

Questions 28, 29, and 30 demonstrate CGI forms and web applications. Each generated project contains a self-contained local Python HTTP server (`server.py`).

To test in your browser:
```bash
cd q28_cgi_login
python server.py
```
Open `http://localhost:8080` in your web browser. You can enter credentials, submit forms, and inspect the CGI responses immediately!

---

## 10. Troubleshooting & FAQ

### "No module named 'numpy'" or other scientific library error
The code generator does not require scientific libraries, but running the generated script might. Run:
```bash
pylab install-deps <question_number>
# Example: pylab install-deps q49
```
Or install all lab dependencies at once:
```bash
pip install -r requirements-labs.txt
```

### "The directory already contains existing files"
To prevent accidental loss of code, `pylab` will not overwrite existing directories. Pass `--force`:
```bash
pylab q12 --force
```

### How can I check if my Python environment is ready?
Run the built-in system diagnostics tool:
```bash
pylab doctor
```

---

## 11. Development & Automated Testing

### Running Tests
The toolkit includes a 56-test automated test suite verifying registry integrity, file generation, syntax correctness, comment absence (Rule A), CLI subcommands, database queries, and program execution.

Run the test suite using standard Python:
```bash
python -m unittest discover -s tests -v
```

### Building Distribution Packages
Build modern wheel and source distributions into `dist/`:
```bash
python setup.py sdist bdist_wheel
```

---

## 12. PyPI Publication Guide

To publish `python-lab-toolkit` to PyPI:

### Step 1: Install Build and Twine Tools
```bash
python -m pip install --upgrade build twine
```

### Step 2: Build Clean Artifacts
```bash
rm -rf dist build src/*.egg-info
python -m build
```

### Step 3: Check Package Metadata with Twine
```bash
python -m twine check dist/*
```

### Step 4: Securely Upload to PyPI using an API Token
```bash
python -m twine upload --username __token__ dist/*
```
When prompted for your password, enter your PyPI API token (`pypi-AgEI...`).

> [!IMPORTANT]
> Never hardcode API tokens or passwords in configuration files or version control. Always use `__token__` and enter the secret token interactively or via the `TWINE_PASSWORD` environment variable.

---

## 13. License & Dataset Attribution

### Package License
This software is distributed under the **MIT License**. See [LICENSE](LICENSE) for full details.

### Dataset Attributions
- **Wine Quality Datasets (`winequality-red.csv`, `winequality-white.csv`)**: P. Cortez, A. Cerdeira, F. Almeida, T. Matos, and J. Reis (2009). Modeling wine preferences by data mining from physicochemical properties. *Decision Support Systems*, Elsevier, 47(4):547-553.
- **Breast Cancer Wisconsin (Diagnostic) Dataset (`breast-cancer.csv`)**: Dr. William H. Wolberg, W. Nick Street, and Olvi L. Mangasarian. UCI Machine Learning Repository.
- **Iris Dataset (`iris.csv`)**: R.A. Fisher (1936). The use of multiple measurements in taxonomic problems. *Annals of Eugenics*, 7, Part II, 179-188.
- **Groceries Dataset (`groceries.csv`)**: Michael Hahsler, Kurt Hornik, and Christian Buchta (2005). arules - Mining Association Rules and Frequent Itemsets.
